Flyboat

Container environment manager for development

Run pre-defined development containers without remembering complex Docker/Podman CLI options. Define once, start anywhere.

Why Flyboat?

When developing, testing, or compiling code, running in a controlled environment helps with:

• Security — Isolate untrusted code from your system
• Reproducibility — Same environment across machines and team members
• Clean system — No dependency pollution on your host machine

Flyboat wraps Docker/Podman with security-first defaults and simple configuration.

Environment

Create your own or Download:

• Basic: https://gitlab.com/flyboat/flyboat-basic-env
• Programming: https://gitlab.com/flyboat/flyboat-programming-env
• Security Scanning: https://gitlab.com/flyboat/flyboat-security-scanning-env
• Security: https://gitlab.com/flyboat/flyboat-security-env
• AI: https://gitlab.com/flyboat/flyboat-ai-env

# Basics
git clone https://gitlab.com/flyboat/flyboat-basic-env.git ~/.flyboat/env/basics
# Programming
git clone https://gitlab.com/flyboat/flyboat-programming-env.git ~/.flyboat/env/programming
# Security Scanning
git clone https://gitlab.com/flyboat/flyboat-security-scanning-env.git ~/.flyboat/env/security-scanning
# Security
git clone https://gitlab.com/flyboat/flyboat-security-env.git ~/.flyboat/env/security
# AI
git clone https://gitlab.com/flyboat/flyboat-ai-env.git ~/.flyboat/env/ai

Prerequisites

Container Engine (one of)

Flyboat currently only supports Linux and macOS.

Note: Docker Desktop requires a paid license for commercial use. Podman is free and open source.

Build Tools

Installation

Easy Install

Linux & Mac OS Only!

[!CAUTION] Don't execute the random code without checking it first.

curl -s https://gitlab.com/flyboat/flyboat/-/raw/main/easy-install.sh | bash
# OR
wget -qO- https://gitlab.com/flyboat/flyboat/-/raw/main/easy-install.sh | bash

Install

Linux & Mac OS Only!

# Clone the repository
git clone https://gitlab.com/flyboat/flyboat.git
cd flyboat

# Install (builds and copies to /usr/local/bin)
./install.sh

The install script will:

1. Build the release binary with cargo build --release
2. Copy the binary to /usr/local/lib/flyboat/
3. Create a symlink at /usr/local/bin/flyboat
4. Copy shell completions files (bash/zsh) to /usr/local/lib/flyboat/
5. Create the environments directory at ~/.flyboat/env/

Shell Completions

After installation, add completions to your shell:

# Bash - add to ~/.bashrc
source /usr/local/lib/flyboat/flyboat.bash

# Zsh - add to ~/.zshrc
autoload -Uz compinit && compinit
source /usr/local/lib/flyboat/flyboat.zsh

Getting Container Environments

Flyboat needs environment definitions (Dockerfile + config) to run containers.

Download Pre-built Environments

See the environment section for a starting list.

# Clone the environments repository
git clone <PLACEHOLDER_ENVIRONMENTS_REPO_URL> ~/.flyboat/env/<namespace>

# Or clone specific environments
git clone <PLACEHOLDER_ENVIRONMENTS_REPO_URL> /tmp/flyboat-envs
cp -r /tmp/flyboat-envs/python ~/.flyboat/env/
cp -r /tmp/flyboat-envs/rust ~/.flyboat/env/

Create Your Own Environment

mkdir -p ~/.flyboat/env/myenv

Create ~/.flyboat/env/myenv/Dockerfile:

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y build-essential
# Setup project directory
WORKDIR /project

# Create dev user (uid/gid 3400) with sudo access, password: dev
RUN groupadd -g 3400 dev && \
    useradd -ms /bin/bash -g 3400 -G sudo -u 3400 dev && \
    echo "dev:dev" | chpasswd && \
    chown dev:dev /project

# Disable root login
RUN passwd root -ld && \
    usermod -s /usr/sbin/nologin root

# Switch to 'dev' user
USER dev

Create ~/.flyboat/env/myenv/dev_env.yaml:

name: myenv
description: My custom development environment
settings:
  network: none        # Most secure (no network access)
  disk_access: mount   # Mount current directory
  entrypoint: bash

Usage

Quick Start

# List available environments
flyboat list

# Run an environment (builds if needed)
flyboat run python

# Run container with additional feature (if defined in `dev_env.yaml`)
flyboat run python+network

CLI Reference

Container environment manager for development

Usage: flyboat [OPTIONS] <COMMAND>

Commands:
  run <env>       Build and start container
  build <env>     Build container image only
  connect <env>   Connect to existing container
  list            List available environments
  status          Show disk usage and running containers
  clean           Remove flyboat images and dangling containers
  help            Print this message or the help of the given subcommand(s)

Global Options:
  -v, --verbose   Verbose output
  -h, --help      Print help
  -V, --version   Print version

Run Options

Build and start container

Usage: flyboat run [OPTIONS] <ENV>

Arguments:
  <ENV>  Environment name

Options:
  -p, --port <PORT>        Port to expose (repeatable)
  -n, --name <NAME>        Container name postfix (default: sanitized current directory name)
  -a, --arch <ARCH>        Architecture: x86, arm64, i386
  -b, --network <NETWORK>  Network mode [default: bridge]
  -r, --run <ENTRYPOINT>   Override entrypoint
      --engine <ENGINE>    Container engine (docker/podman)
      --rebuild            Force rebuild image (--no-cache)
  -v, --verbose            Verbose output
      --dry-run            Show commands without executing
  -h, --help               Print help
  -V, --version            Print version

Supported architectures:

Examples

# Run Python with port 8000 exposed
flyboat run python -p 8000

# Map host port 3000 to container port 80
flyboat run python -p 3000:80

# Expose multiple ports
flyboat run python -p 8080 -p 3000

# Run with custom container name
flyboat run rust -n myproject

# Cross-architecture build (e.g., ARM on x86)
flyboat run rust -a arm64

# Connect to already running container
flyboat connect python -n myproject

# List environments
flyboat list

Note: Containers are interactive (-it) and auto-remove on exit (--rm) by default.

Configuration

Global Config

Location: ~/.flyboat/config.yaml

container_engine: podman   # docker or podman
arch: arm64                # Default architecture
default_env: python        # Default environment

Environment Config

Each environment has a dev_env.yaml:

name: python
disable: false            # Exclude from list/run/build (default: false)
description: Python development environment
version: "3.12"
author: Jane Doe          # Optional
source: https://example.com/env  # Optional URL

settings:
  network: none           # none (default), bridge, host, or custom name
  disk_access: mount      # none (default), mount, readonly, tmpfs
  entrypoint: bash        # Default shell/command
  working_dir: /app       # Container working directory (default: /project)
  artifacts_folder: false # Create /artifacts mount

aliases:
  - py
  - python3

mounts:
  - host_path: /home/user/data
    container_path: /data
    read_only: true       # Default: true

custom_args:
  - "-e"
  - "SOME_VAR=1"

# Optional: Feature variants
features:
  network:
    settings:
      network: bridge
  gpu:
    custom_args: ["--gpus=all"]

# Optional: Template file processing
templates:
  - source: config.example.toml   # Template file path (relative to env folder)
    overwrite: if_not_exists      # if_not_exists (default), on_build, on_run
    variables:
      api_key:
        type: random
        charset: alphanumeric     # alphanumeric, lowercase, uppercase, mixedcase, numbers, hex, bytes
        length: 32
      db_host:
        type: fixed
        value: localhost

Disk access modes:

Features

Activate features with + syntax:

flyboat run python+network       # Enable networking
flyboat run python+gpu+network   # Multiple features

Templates

Generate config files with variable substitution. Template files use {{var_name}} placeholders.

Output naming: config.example.toml → config.toml (removes .example segment)

Overwrite modes:

Variable types:

Random charsets:

Note: bytes charset requires encoding: base64 for safe output.

Directory Structure

~/.flyboat/
├── config.yaml              # Global configuration
└── env/                     # Environment definitions
    ├── python/
    │   ├── Dockerfile
    │   └── dev_env.yaml
    ├── rust/
    │   ├── Dockerfile
    │   └── dev_env.yaml
    └── my_collection/       # Namespaced environments
        └── custom/
            ├── Dockerfile
            └── dev_env.yaml

Access namespaced environments:

flyboat run my_collection/custom

Security

Flyboat uses secure defaults:

• Network: none — No network access by default
• Disk: none — No host filesystem access by default
• Ports: 127.0.0.1 — Exposed ports bind to localhost only
• Safe directories — Refuses to run from /, /root, /home, or $HOME
• Podman — Preferred for rootless containers with user namespace mapping

Important: Always run flyboat from within a project directory, not from system directories.

Uninstall

/usr/local/lib/flyboat/uninstall.sh

# Or manually remove
sudo rm /usr/local/bin/flyboat
sudo rm -r /usr/local/lib/flyboat

# Optionally remove environments and config
rm -r ~/.flyboat

License

The code in this project is licensed under the MIT license.

All contributions, code and documentation, to this project will be similarly licensed.