# 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)

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

### With pip

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

### With pipx (isolated global install)

```bash
pipx install .
```

## Quick Start

```bash
# 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

| Runtime | Platform | Use Case |
|---------|----------|----------|
| Docker | Linux, macOS | General purpose, wide compatibility |
| systemd-nspawn | Linux | Lightweight, native systemd integration |
| libvirt/QEMU | Linux | Full VM isolation for untrusted workloads |

## Profiles

Apply pre-configured profiles to containers:

```bash
# 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:

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

```bash
gaol spec apply mycontainer.yaml --start
```

## Container Diff

Compare container filesystems and track changes:

```bash
# 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

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

# Run tests
uv run pytest

# Run linter
uv run ruff check src/
```

## License

MIT
