# 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
<a name="environments"></a>
[Create your](#create_env) own or [Download](#download_env):
- 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
<details>
<summary><b>Install Environment commands</b></summary>
```bash
# 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
```
</details>
---
## Prerequisites
### Container Engine (one of)
| Podman | Linux, macOS | [podman.io](https://podman.io/) |
| Podman Desktop | Linux, macOS | [podman-desktop.io](https://podman-desktop.io/downloads) |
| Docker Engine | Linux | [docs.docker.com](https://docs.docker.com/engine/install/) |
| Docker Desktop | Linux, macOS | [docs.docker.com](https://docs.docker.com/desktop/) |
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
| Rust | Building from source | [rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) |
| Git | Cloning repositories | ... |
---
## Installation
### Easy Install
Linux & Mac OS Only!
> [!CAUTION]
> Don't execute the random code without checking it first.
```bash
curl -s https://gitlab.com/flyboat/flyboat/-/raw/main/easy-install.sh | bash
wget -qO- https://gitlab.com/flyboat/flyboat/-/raw/main/easy-install.sh | bash
```
### Install
Linux & Mac OS Only!
```bash
# 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
# 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
<a name="download_env"></a>
See the [environment](#environments) section for a starting list.
```bash
# 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
<a name="create_env"></a>
```bash
mkdir -p ~/.flyboat/env/myenv
```
Create `~/.flyboat/env/myenv/Dockerfile`:
```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`:
```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
```bash
# 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:**
| `x86`, `x86_64`, `amd64` | linux/amd64 |
| `arm64`, `aarch64` | linux/arm64 |
| `i386`, `i686`, `386` | linux/386 |
### Examples
```bash
# 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`
```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`:
```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:**
| Mode | Behavior |
|------|----------|
| `none` | No host filesystem access (most secure, default) |
| `mount` | Mount current directory read-write to working_dir |
| `readonly` | Mount current directory read-only to working_dir |
| `tmpfs` | Temporary in-memory filesystem (data lost on exit) |
### Features
Activate features with `+` syntax:
```bash
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:**
| `if_not_exists` | Only generate if output doesn't exist (default) |
| `on_build` | Generate during `flyboat build` |
| `on_run` | Generate during `flyboat run` (refresh random values each run) |
**Variable types:**
| `fixed` | Static value from config |
| `random` | Generated value with specified charset and length |
**Random charsets:**
| `alphanumeric` | `a-z`, `A-Z`, `0-9` |
| `lowercase` | `a-z` |
| `uppercase` | `A-Z` |
| `mixedcase` | `a-z`, `A-Z` |
| `numbers` | `0-9` |
| `hex` | `0-9`, `a-f` |
| `bytes` | Any byte (0-255), requires `encoding: base64` |
> **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:
```bash
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
```bash
/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.