# Gaol Development Plan

## Current Status

- Core models (ContainerConfig, ContainerState, Profile, Snapshot, HealthCheck)
- Docker runtime (fully implemented with profile application, snapshots, stats)
- systemd-nspawn runtime (fully implemented with profile application, snapshots)
- libvirt/QEMU runtime (fully implemented for full VM isolation)
- CLI with comprehensive commands including profiles, runtimes, snapshots, secrets, security
- Profile system with 10+ built-in profiles
- ProfileApplicator for merging and applying profiles to containers
- ContainerStore for persisting container configurations
- Declarative specs (YAML/TOML container specifications with `apply` command)
- Secrets management (encrypted secrets with `${secret:NAME}` syntax)
- Monitoring module with health checks (HTTP, TCP, command)
- SSH config generation for containers
- Distro abstraction layer for package/service translation
- Networking module with port mapping, DNS config, bridge support
- Security module with Falco integration, seccomp/AppArmor profile generation
- Container groups module for pod-like orchestration
- VS Code devcontainer.json support (import/export/generate)
- Runtime migration between Docker, nspawn, and libvirt
- Log aggregation with centralized collection, search, and retention policies
- Desktop integration for containerized GUI apps with XDG .desktop files
- Homebrew wrapper for transparent containerized package execution
- Dev tunnels for exposing containers to the internet (cloudflared)
- Shell integration (completions, prompt, context management)
- GPU passthrough for NVIDIA, AMD, and Intel GPUs
- Remote host management (SSH execution, config sync)
- Container diff for comparing filesystems and auditing changes
- Build from container (Dockerfile generation, image building, registry push)
- Template Gallery with 14 built-in templates across 6 categories
- Profile/Spec Sharing with URL import and security scanning
- Apple Containers runtime for native macOS/Apple Silicon support
- Nix integration for reproducible container environments with flakes
- 1534 tests passing

## Completed Features

### High Priority (Core Functionality)

- [x] **Profile Application During Container Creation**
  - Install packages, run setup commands, enable services, set environment
  - Merge profile settings into container config
  - Apply profiles in dependency order

- [x] **Container Configuration Persistence**
  - Store container configs in `~/.config/gaol/containers/`
  - Allow recreating containers from saved configs
  - Enable `gaol inspect <name>` to show full config

- [x] **Multi-Runtime Container Listing**
  - `gaol list --all-runtimes` to show containers from all runtimes
  - Auto-detect which runtime a container belongs to

### Medium Priority (Usability)

- [x] **File Copy Commands**
  ```bash
  gaol cp local/file container:/path
  gaol cp container:/path local/file
  ```

- [x] **Container Snapshots**
  - `gaol snapshot create <container> <name>`
  - `gaol snapshot restore <container> <name>`
  - `gaol snapshot list <container>`
  - `gaol snapshot delete <container> <name>`

- [x] **libvirt/QEMU Runtime** (for full VM isolation)
  - Heavier but more secure for untrusted workloads
  - Cloud-init support for VM provisioning
  - Domain XML generation

- [x] **Profile Validation Command**
  ```bash
  gaol profiles validate ./my-profile.yaml
  ```

- [x] **SSH Config Generation**
  ```bash
  gaol ssh-config <container>  # Generate ~/.ssh/config entries
  gaol ssh-config --append     # Append directly to config file
  ```

- [x] **Declarative Container Specs**
  ```yaml
  # container.yaml
  name: dev-env
  runtime: docker
  image: debian:bookworm
  profiles: [base, dev-python]
  environment:
    DATABASE_URL: "postgres://user:${secret:DB_PASS}@localhost/db"
  ports:
    - "8080:80"
  ```
  ```bash
  gaol apply container.yaml --start
  ```

- [x] **Secrets Management**
  - Encrypted storage using AES-256-GCM
  - Master key stored in system keyring (GNOME Keyring, macOS Keychain, Windows Credential Manager)
  - Environment variable fallback (`GAOL_MASTER_KEY`)
  - `${secret:NAME}` syntax for referencing secrets in environment variables
  ```bash
  gaol secret init
  gaol secret create DB_PASSWORD
  gaol secret list
  gaol secret show DB_PASSWORD
  ```

- [x] **Monitoring and Health Checks**
  - ContainerMonitor for resource tracking
  - HealthChecker with HTTP, TCP, and command checks
  - `gaol stats <container>` for resource usage

- [x] **Container Export/Import**
  ```bash
  gaol export <container> output.tar
  gaol import input.tar <name>
  ```

- [x] **Security Monitoring with Falco**
  - Falco gRPC client for real-time event streaming
  - Auto-installation support (apt, dnf, yum, zypper)
  - Custom rule management (create, enable, disable, import/export)
  - Built-in security rules for container threat detection
  - seccomp profile generation (OCI format) with learning mode
  - AppArmor profile generation with learning mode
  ```bash
  gaol security init --auto-install
  gaol security status
  gaol security events --follow --container myapp
  gaol security rules list
  gaol security rules install-builtin
  gaol security policy generate mycontainer --type seccomp
  gaol security policy generate mycontainer --type apparmor --learn
  ```

- [x] **Container Groups (Pod-like Orchestration)**
  - GroupSpec for declarative group definitions
  - Dependency resolution with topological sorting
  - Shared networking via Docker networks or Linux bridges
  - Service discovery between grouped containers
  - `depends_on` ordering for startup/shutdown
  - GroupStore for persistence at `~/.config/gaol/groups/`
  ```yaml
  # group.yaml
  name: web-stack
  shared_network: true
  containers:
    db:
      image: postgres:16
      healthcheck:
        type: tcp
        port: 5432
    api:
      image: python:3.11
      depends_on: [db]
      ports: ["8000:8000"]
    web:
      image: nginx:alpine
      depends_on: [api]
      ports: ["80:80"]
  ```
  ```bash
  gaol group up group.yaml
  gaol group status web-stack
  gaol group logs web-stack --container api
  gaol group exec web-stack api -- python manage.py migrate
  gaol group down web-stack
  ```

- [x] **VS Code Devcontainer Support**
  - Read/write `.devcontainer/devcontainer.json` for IDE integration
  - Convert gaol specs to devcontainer format and vice versa
  - Support devcontainer features and lifecycle scripts
  - JSONC parsing (comments supported)
  ```bash
  gaol devcontainer import [path] -o container.yaml
  gaol devcontainer export container.yaml --output-dir .devcontainer
  gaol devcontainer generate my-container
  gaol devcontainer validate
  gaol devcontainer show
  gaol devcontainer init --image python:3.11
  gaol devcontainer init --profile dev-python
  ```

- [x] **Runtime Migration**
  - Move containers between runtimes (Docker → nspawn, Docker → libvirt, etc.)
  - Export filesystem via tarballs and re-import on different runtime
  - Feature translation with warnings for incompatible settings
  - Dry-run mode for previewing changes
  - Rollback on failure
  ```bash
  gaol migrate mycontainer --to nspawn
  gaol migrate mycontainer --to libvirt --dry-run
  gaol migrate mycontainer --to docker --no-preserve-source
  gaol migrate mycontainer --to nspawn --force -v
  ```

- [x] **Log Aggregation**
  - Centralized log collection across all runtimes
  - JSONL storage with automatic rotation and retention policies
  - Full-text search with regex support and time filtering
  - Pattern analysis for recurring issues
  - Log level parsing from message content
  - Export to text and JSONL formats
  ```bash
  gaol logs search mycontainer --since 1h --level error
  gaol logs search --all --pattern "ERROR" --regex
  gaol logs collect --runtime docker --interval 30
  gaol logs stats mycontainer
  gaol logs summary mycontainer
  gaol logs export mycontainer --format jsonl
  gaol logs rotate --all
  ```

- [x] **Desktop Integration**
  - Generate XDG `.desktop` files for containerized GUI apps
  - Menu entries with proper categorization
  - Auto-start containers when launching apps
  - Icon extraction from containers
  - X11/Wayland forwarding support
  ```bash
  gaol desktop create my-browser /usr/bin/firefox --name "Firefox" --icon firefox
  gaol desktop list
  gaol desktop show my-browser
  gaol desktop uninstall my-browser --all
  gaol desktop run --start my-container -- /usr/bin/xeyes
  gaol desktop extract-icon my-container /usr/share/icons/app.png
  ```

## Remaining Features

### Lower Priority (Nice to Have)

- [x] **Apple Containers Runtime** (Mac support) ✅
  - Native macOS Virtualization.framework via Apple's `container` CLI
  - Subprocess calls to Apple's official container tool (github.com/apple/container)
  - Supports macOS 15+ on Apple Silicon
  - Full runtime implementation: create, start, stop, exec, logs, stats, snapshots
  ```bash
  gaol create --runtime apple mycontainer
  gaol --runtime apple list
  gaol exec mycontainer -- uname -a
  ```

## Roadmap

### Developer Experience

- [x] **Dev Tunnels (Quick)**
  - Expose containers to the internet via cloudflared quick tunnels
  - Webhook testing, demos, temporary public access
  - Automatic port mapping detection from container config
  - Process management with PID tracking
  - YAML persistence for tunnel state
  ```bash
  gaol tunnel start mycontainer 8080
  gaol tunnel list
  gaol tunnel stop <tunnel-id>
  gaol tunnel stop-all --container mycontainer
  ```

- [ ] **Named Tunnels (Cloudflare)**
  - Persistent tunnels with custom domains (e.g., code.example.com)
  - Cloudflare account authentication and credential management
  - Automatic DNS CNAME creation via Cloudflare API
  - Systemd service generation for persistent tunnels
  - Multi-hostname ingress rules (multiple services per tunnel)
  - Spec-level `tunnel` config for declarative setup
  ```yaml
  # In spec YAML:
  tunnel:
    provider: cloudflare
    hostname: code.example.com
    service: http://localhost:8080
  ```
  ```bash
  gaol tunnel create mycontainer --hostname code.example.com
  gaol tunnel dns mycontainer code.example.com
  gaol tunnel install mycontainer   # Install as systemd service
  gaol tunnel status mycontainer
  ```

- [x] **Shell Integration**
  - Fish/Zsh/Bash completions for all commands
  - Prompt integration showing active container context
  - Container context management with helper functions
  - Shell helper functions: muse, munuse, msh, mstatus, mexec, mstart, mstop, mlogs
  ```bash
  gaol shell-integration completions bash --install
  gaol shell-integration prompt zsh >> ~/.zshrc
  eval "$(gaol shell-integration init bash)"
  muse mycontainer   # Set container context
  msh                # Shell into current container
  mexec ls -la       # Execute in current container
  ```

- [ ] **IDE Plugins**
  - JetBrains (IntelliJ, PyCharm, etc.) integration
  - Neovim/Vim plugin for container-aware development
  - Emacs integration
  - Container-aware language servers and debuggers

- [ ] **`gaol dx` — Python CLI for dx functionality**
  - The bash scripts under `scripts/dev/` (dx, dev.sh, overlays, templates) are host-level
    operational tooling tightly coupled to systemd-nspawn, machinectl, sudo, and labwc
  - They are NOT included in the PyPI package — only `src/gaol/` ships in the wheel
  - They rely on relative paths (`$SCRIPT_DIR/overlays/`, `$SCRIPT_DIR/state/`) that only
    make sense in the repo checkout
  - If dx functionality is needed via `pip install gaol`, reimplement as a Python CLI command
    (`gaol dx`) using the existing library (devcontainer loader, converter, models) rather than
    bundling the bash scripts — different audiences, different distribution mechanism

### Domain-Based Security

Lightweight domain-based security patterns using systemd-nspawn containers.

- [x] **Template Containers** (Phase 1) ✅
  - Base images that spawn app containers using OverlayFS
  - Read-only templates with ephemeral overlays for app containers
  - Template versioning and update propagation
  - Instant cloning via btrfs/ZFS snapshots
  ```bash
  gaol template-container create debian-base --distro trixie --profiles base,dev
  gaol template-container list
  gaol template-container spawn debian-base myapp --ephemeral
  gaol template-container spawn debian-base myworkspace --persistent
  gaol template-container update debian-base
  ```

- [x] **Disposable Containers** (Phase 1) ✅
  - Ephemeral containers destroyed after use (like DispVMs)
  - Fresh state every launch, changes discarded on shutdown
  - Pre-configured disposable types (browser, file-viewer, terminal)
  - Desktop launchers for one-click disposable apps
  - Optional path preservation (e.g., ~/Downloads)
  ```bash
  gaol disposable create browser --template debian-browser
  gaol disposable launch browser              # Start fresh instance
  gaol disposable launch browser --keep-downloads
  gaol disposable open-file untrusted.pdf     # Open in disposable viewer
  gaol disposable list                        # Show configured disposables
  gaol disposable desktop browser             # Create .desktop launcher
  ```

- [x] **Security Domains** (Phase 1) ✅
  - Color-coded trust levels (vault, work, personal, untrusted, disposable)
  - Domain-based policies (network access, resource limits, profiles)
  - Visual indicators in terminal and desktop launchers
  - Inter-domain communication rules
  ```bash
  gaol domain create work --color "#0066B3" --allow-internet
  gaol domain create vault --color "#800080" --no-network
  gaol domain create untrusted --color "#CC0000" --ephemeral-only
  gaol domain list
  gaol domain assign mycontainer work
  gaol create --domain work myworkspace
  ```

- [ ] **Service Containers** (Phase 2)
  - Dedicated containers providing network services (sys-firewall, sys-tor, sys-vpn)
  - Route other containers' traffic through service containers
  - Kill switch and DNS leak prevention
  - Already 70% implemented in privacy module
  ```bash
  gaol service-container create vpn-gateway --type vpn --config mullvad.conf
  gaol service-container create tor-gateway --type tor
  gaol service-container attach myapp --gateway vpn-gateway
  gaol service-container status vpn-gateway
  ```

- [ ] **Split Secrets Vault** (Phase 2)
  - Private keys isolated in vault container
  - GPG/SSH agent socket forwarding with policy control
  - Keys never leave vault, signing requests proxied
  ```bash
  gaol vault create myvault --type gpg
  gaol vault import-key myvault ~/.gnupg/private.key
  gaol vault allow myvault --container work --operations sign
  gaol vault attach work --vault myvault
  # In work container: gpg --sign file.txt  # Key stays in vault
  ```

- [ ] **Network Chains** (Phase 3)
  - Multi-hop routing: app → firewall → gateway
  - Policy enforcement at each hop
  - Traffic logging and filtering
  ```bash
  gaol chain create secure-web app:myapp firewall:sys-firewall gateway:sys-tor
  gaol chain status secure-web
  gaol chain logs secure-web --hop firewall
  ```

- [ ] **Open vSwitch for inter-container networking** (Phase 3+)
  - Internal-only OVS bridge alongside br0 (host uplink stays on Linux bridge)
  - VLAN tagging for L2 isolation between containers that need to communicate
  - Per-flow statistics and debugging via `ovs-ofctl dump-flows`
  - Foundation for multi-host overlays (OVN/GENEVE tunnels over WireGuard mesh)
  - Not needed for chain topologies (private veths + nftables already handle isolation)

- [ ] **Inter-Container RPC** (Phase 3)
  - Policy-controlled communication between containers (like qrexec)
  - Service registration and discovery
  - Fine-grained permissions per operation
  ```bash
  gaol rpc register file-viewer --container disp-viewer --command "xdg-open"
  gaol rpc policy add --service file-viewer --from work --action allow
  gaol rpc call file-viewer --from work -- /path/to/file.pdf
  ```

- [x] **Host Service Migration** ✅
  - Migrate host systemd services into nspawn containers
  - Parse systemd unit files ([Unit], [Service], [Install] sections)
  - Auto-discover dependencies (packages via dpkg, config files, ports, state directories)
  - Well-known services registry for common services (nginx, postgres, redis, etc.)
  - Generate container specs from service analysis
  - Handle edge cases (template services, socket activation, drop-in files)
  ```bash
  gaol service migrate nginx --dry-run        # Analyze without creating
  gaol service migrate postgres --output postgres.yaml  # Generate spec
  gaol service migrate redis -i               # Interactive mode
  gaol service migrate myapp --copy-config --copy-data  # Full migration
  ```

### AI & Agent Integration

- [x] **Claude Code Skills & Commands**
  - Custom Claude Code skills for container management
  - `/container` command for container lifecycle operations
  - `/profile` command for profile management
  - `/spec` command for spec file management
  - `/msetup` command for automatic project setup
  - `/gpu` command for GPU management
  - Context-aware container suggestions
  - Automated container creation from project analysis
  ```bash
  # In Claude Code:
  /container create myapp with python
  /container exec myapp pytest
  /msetup              # Auto-detect and setup
  /gpu check           # Verify GPU support
  /spec create myapp   # Interactive spec creation
  ```

- [x] **AGENT.md Documentation**
  - Comprehensive guide for AI agents using gaol
  - CLI command reference with examples
  - Common workflows and patterns
  - Error handling and troubleshooting
  - Container lifecycle management
  - Profile and spec file formats
  - Integration patterns for autonomous agents

### Privacy & Security

- [x] **Privacy Networking**
  - Transparent Tor proxy for entire containers (all traffic routed through Tor)
  - VPN gateway containers (route other containers' traffic through VPN)
  - WireGuard mesh networking between containers across hosts
  - Tor hidden services (.onion addresses) for container services
  - DNS leak prevention and kill switch
  ```bash
  gaol create --profile tor-transparent mycontainer  # All traffic via Tor
  gaol network tor-proxy create mytor --container myapp
  gaol network tor-proxy create mytor --container myapp --transparent
  gaol network onion create web-service --container nginx --port 80
  gaol network onion address web-service  # Shows .onion address
  gaol network vpn-gateway create vpn1 --config ~/vpn/client.ovpn --provider openvpn
  gaol network wireguard create mesh1 --subnet 10.200.0.0/24
  gaol network wireguard add-peer mesh1 --peer-name peer1 --public-key KEY --peer-ip 10.200.0.2
  ```

- [x] **Encrypted Storage**
  - LUKS-encrypted volumes for container data (block-level encryption)
  - gocryptfs overlays for transparent file-level encryption
  - Per-volume encryption keys (stored in secrets module)
  - Automatic key generation and secure storage
  ```bash
  gaol volume create mydata --size 2048
  gaol volume create secrets --type gocryptfs
  gaol volume unlock mydata
  gaol volume lock mydata
  gaol volume list
  gaol volume show mydata
  gaol volume delete mydata --force
  ```

### Storage

- [x] **Copy-on-Write Filesystems** ✅
  - btrfs subvolume-based container storage
  - ZFS dataset support with native snapshots
  - Instant container clones (no data copy)
  - Efficient incremental backups via send/receive
  - Storage pools with quotas and compression
  ```bash
  gaol cow init mypool /mnt/btrfs --backend btrfs
  gaol cow init tank /tank --backend zfs --compression lz4
  gaol cow dataset-create mypool/containers
  gaol cow snapshot-create mypool/containers@v1  # Instant snapshot
  gaol cow clone mypool/containers@v1 containers-test  # Instant clone
  gaol cow send mypool/containers@v1 -o backup.stream
  gaol cow receive mypool backup.stream
  ```

### Infrastructure

- [x] **Remote Management** *(completed)*
  - Manage containers on remote hosts via SSH
  - Sync configurations between machines
  - Remote command execution
  ```bash
  gaol --host user@server list
  gaol --host user@server exec mycontainer -- cmd
  gaol remote add production user@prod-server
  gaol remote sync mycontainer --to production
  ```

- [x] **Checkpoint/Restore (CRIU)** ✅
  - Pause containers and save full state to disk
  - Resume later or on different machine
  - Live migration between hosts
  ```bash
  gaol checkpoint create mycontainer checkpoint-1
  gaol checkpoint restore mycontainer checkpoint-1
  gaol checkpoint list mycontainer
  gaol checkpoint migrate mycontainer --to user@other-host
  ```

- [x] **GPU Passthrough**
  - First-class NVIDIA GPU support with nvidia-container-toolkit
  - AMD ROCm support
  - Intel GPU support
  - Automatic driver detection and configuration
  ```bash
  gaol gpu list  # Show available GPUs
  gaol gpu check  # Check driver/runtime support
  gaol create --gpu mycontainer
  gaol create --gpu --gpu-device 0 mycontainer
  gaol exec mycontainer -- nvidia-smi
  ```

### Operations

- [x] **Scheduled Backups** ✅
  - Automatic container backups with daily/weekly/monthly scheduling
  - Retention policies (keep last N, keep daily/weekly/monthly, max age, max size)
  - Cloud storage support (local filesystem, S3-compatible)
  - Full and incremental backups using CoW snapshots
  ```bash
  gaol backup create mycontainer --name daily-backup
  gaol backup schedule mycontainer daily --time 02:00
  gaol backup list mycontainer
  gaol backup restore mycontainer daily-backup
  gaol backup config --storage s3://mybucket/backups
  ```

- [x] **Auto-Update**
  - Automatically update base images and packages
  - Configurable update schedules (daily, weekly, monthly)
  - Automatic rollback on failure with pre-update snapshots
  - Update history and reporting
  ```bash
  gaol update check mycontainer
  gaol update apply mycontainer
  gaol update schedule mycontainer daily --time 03:00
  gaol update schedule mycontainer weekly --day 6 --time 02:00
  gaol update history mycontainer
  gaol update list
  gaol update enable mycontainer
  gaol update disable mycontainer
  ```

- [x] **Metrics Export** ✅
  - Prometheus endpoint for container metrics
  - Grafana dashboard templates
  - Resource usage alerts
  - Historical metrics storage
  ```bash
  gaol metrics serve --port 9100  # Prometheus endpoint
  gaol metrics export [container...]
  gaol metrics dashboard > dashboard.json
  gaol metrics alert add high-cpu --metric cpu --threshold 80
  gaol metrics alert status
  ```

### Reproducibility

- [x] **Nix Integration** ✅
  - Use Nix for fully reproducible container environments
  - Declarative package management with pinned versions (100+ package mappings)
  - Nix flake support for container definitions with `flake.nix` generation
  - nix-shell and nix develop support for ephemeral environments
  - Package installation via nix-env for persistent packages
  - Package search and garbage collection commands
  ```bash
  gaol nix init mycontainer  # Install Nix in container
  gaol nix status mycontainer  # Check Nix status
  gaol nix shell mycontainer --packages python311 nodejs
  gaol nix install mycontainer python311 nodejs
  gaol nix search mycontainer python
  gaol nix flake init mycontainer /app --packages python311
  gaol nix flake develop mycontainer /app
  gaol nix gc mycontainer  # Garbage collect
  ```

- [x] **Container Diff**
  - Compare container filesystem states
  - Audit changes over time
  - Show package differences between containers
  - Track configuration drift
  ```bash
  gaol diff containers container-a container-b
  gaol diff snapshots mycontainer --from snap1 --to snap2
  gaol diff baseline mycontainer --image debian:trixie
  gaol audit mycontainer --packages
  ```

- [x] **Build from Container** ✅
  - Export running container to Dockerfile
  - Generate OCI image from container state
  - Push to container registries
  - Reproducible image builds (commit or dockerfile methods)
  ```bash
  gaol build dockerfile mycontainer -o Dockerfile
  gaol build image mycontainer --tag myapp:latest
  gaol build image mycontainer --method dockerfile --repo myapp
  gaol build push myapp:latest --registry ghcr.io/user
  gaol build history myapp:latest
  gaol build list  # Show gaol-built images
  ```

### Sharing

- [x] **Template Gallery** ✅
  - Curated templates for common setups (14 built-in templates)
  - Categories: web-dev, data-science, devops, database, gaming, security
  - One-command instantiation with post-create scripts
  - Remote gallery support with caching
  - User template store in `~/.config/gaol/templates/`
  ```bash
  gaol template list
  gaol template list --category web-dev --local
  gaol template search "python web"
  gaol template info web-dev/django
  gaol template use web-dev/django myproject --start
  gaol template create mycontainer --id custom/my-template
  gaol template categories
  gaol template refresh
  gaol template delete custom/my-template
  ```

- [x] **Profile/Spec Sharing** ✅
  - Import profiles and specs from URLs (https://, github:, gist:)
  - Auto-detect content type (profile vs spec)
  - Security scanning for dangerous content (command injection, sensitive mounts, credentials)
  - Local storage in `~/.config/gaol/profiles/imported/` and `~/.config/gaol/specs/imported/`
  ```bash
  gaol import https://example.com/profile.yaml
  gaol import github:user/repo/profiles/dev.yaml
  gaol import github:user/repo/specs/web.yaml@develop --type spec
  gaol profiles import gist:abc123/my-profile.yaml --name my-dev
  gaol spec import https://example.com/container.yaml
  ```

- [x] **Homebrew Wrapper**
  - Run Homebrew packages in isolated containers
  - Transparent execution with wrapper scripts in `~/.local/bin/`
  - Shared container with home directory mounted
  ```bash
  gaol brew install ffmpeg  # Installs in isolated container
  gaol brew run ffmpeg -- -i input.mp4 output.webm
  gaol brew list
  gaol brew uninstall ffmpeg
  gaol brew search video
  gaol brew info ffmpeg
  ```

## Architecture (Current)

```
src/gaol/
├── models/          # Pydantic models (ContainerConfig, Profile, Snapshot, etc.)
├── runtimes/        # Runtime implementations (Docker, nspawn, libvirt, Apple)
├── profiles/        # Profile system (loader, applicator, built-in profiles)
├── secrets/         # Secrets management (crypto, keyring, store, resolver)
├── monitoring/      # Health checks and resource monitoring
├── networking/      # Port mapping, DNS, bridge configuration
├── specs/           # Declarative YAML/TOML spec handling
├── security/        # Falco integration, seccomp, AppArmor, security rules
├── groups/          # Container group orchestration (pod-like)
├── devcontainer/    # VS Code devcontainer.json support
├── migration/       # Runtime migration utilities
├── logs/            # Log aggregation, storage, and search
├── desktop/         # XDG desktop integration for GUI apps
├── brew/            # Homebrew wrapper for containerized packages
├── tunnel/          # Dev tunnels via cloudflared
├── shell/           # Shell integration (completions, prompt)
├── gpu/             # GPU passthrough (NVIDIA, AMD, Intel)
├── privacy/         # Privacy networking (Tor, VPN, WireGuard, firewall)
├── storage/         # Encrypted storage (LUKS, gocryptfs volumes)
├── cow/             # Copy-on-Write filesystems (btrfs, ZFS)
├── remote/          # Remote host management (SSH execution, config sync)
├── diff/            # Container filesystem diff and audit
├── build/           # Build images from containers (Dockerfile, registry push)
├── templates/       # Template gallery (builtin templates, store, remote gallery)
├── sharing/         # Profile/spec sharing (URL import, security scanning)
├── nix/             # Nix integration (installer, shell, flakes, package translation)
├── store.py         # Container configuration persistence
├── distro.py        # Distribution abstraction layer
├── config.py        # Application configuration
└── cli.py           # Typer CLI application

.claude/
├── commands/        # Claude Code skills
│   ├── container.md # /container command
│   ├── profile.md   # /profile command
│   ├── spec.md      # /spec command
│   ├── msetup.md    # /msetup command
│   └── gpu.md       # /gpu command
└── settings.local.json
```

