gaol

Containers and VMs all the way down.

A cross-platform container and VM management tool supporting Docker, systemd-nspawn, and libvirt.

Installation

With uv (recommended)

git clone <repo-url>
cd gaol
uv pip install -e .

With pip

git clone <repo-url>
cd gaol
pip install -e .

With pipx (isolated global install)

pipx install .

Quick Start

# Create a container
gaol create mycontainer --distro trixie

# Start the container
gaol start mycontainer

# Execute a command
gaol exec mycontainer -- bash

# List containers
gaol list

# Stop and destroy
gaol stop mycontainer
gaol destroy mycontainer

Features

• Multiple runtimes: Docker, systemd-nspawn, libvirt/QEMU
• Profiles: Reusable configurations for common setups (dev tools, GUI, networking)
• Snapshots: Save and restore container state
• Declarative specs: Define containers in YAML/TOML files
• Secrets management: Encrypted secrets with ${secret:NAME} syntax
• GPU passthrough: NVIDIA, AMD, and Intel GPU support
• Container diff: Compare filesystem states and audit changes
• Health checks: HTTP, TCP, and command-based monitoring
• Dev tunnels: Expose containers to the internet via cloudflared
• Shell integration: Completions and prompt integration for bash/zsh/fish

Runtimes

Profiles

Apply pre-configured profiles to containers:

# Create with profiles
gaol create mydev --distro trixie --profile dev-python --profile gui

# List available profiles
gaol profiles list

# Show profile details
gaol profiles show dev-python

Built-in profiles include: base, dev-python, dev-node, dev-rust, gui, tailscale, tor, docker-in-docker, and more.

Declarative Specs

Define containers in YAML:

# mycontainer.yaml
name: web-dev
runtime: nspawn
distro: trixie
profiles:
  - dev-python
  - gui
environment:
  DATABASE_URL: "postgres://localhost/mydb"
ports:
  8080: 80

gaol spec apply mycontainer.yaml --start

Container Diff

Compare container filesystems and track changes:

# Compare two containers
gaol diff containers container-a container-b

# Compare snapshots
gaol diff snapshots mycontainer --from baseline --to current

# Audit changes since last snapshot
gaol audit mycontainer --packages

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run linter
uv run ruff check src/

License

MIT