Metadata-Version: 2.4
Name: gaol
Version: 2026.2.2
Summary: Cross-platform container and VM management tool
Author: erewhon
License: MIT
License-File: LICENSE
Keywords: containers,docker,libvirt,systemd-nspawn,virtualization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0.0
Requires-Dist: docker>=7.0.0
Requires-Dist: grpcio>=1.60.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: prometheus-client>=0.20.0
Requires-Dist: protobuf>=4.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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
