# Gaol Agent Guide

This document provides comprehensive guidance for AI agents using gaol to manage containers and VMs. It covers all CLI commands, common workflows, and best practices for autonomous container management.

## Overview

Gaol is a cross-platform container and VM management tool supporting:
- **Docker** - Standard container runtime (Linux/Mac)
- **systemd-nspawn** - Lightweight Linux containers
- **libvirt/QEMU** - Full VM isolation for untrusted workloads

Key features:
- Profile-based configuration (reusable container recipes)
- Declarative YAML/TOML specs
- GPU passthrough (NVIDIA, AMD, Intel)
- Secrets management with encryption
- Container groups (pod-like orchestration)
- Dev tunnels for public access
- Desktop integration for GUI apps

## Quick Reference

### Container Lifecycle

```bash
# Create a container
gaol create <name> [--runtime docker|nspawn|libvirt] [--profile <profile>]

# Start/stop/destroy
gaol start <name>
gaol stop <name> [--timeout 10]
gaol destroy <name> [--force]

# Execute commands
gaol exec <name> -- <command>
gaol shell <name>

# Status and inspection
gaol list [--all-runtimes]
gaol status <name>
gaol stats <name>
gaol inspect <name>
gaol logs <name> [--follow]
```

### Declarative Specs

```bash
# Apply a spec file (create or update)
gaol apply <spec.yaml> [--start]

# Spec management
gaol spec init <name> [--runtime docker]
gaol spec validate <spec.yaml>
gaol spec show <spec.yaml>
gaol spec export <container> -o spec.yaml
```

### Profiles

```bash
# List and inspect profiles
gaol profiles list
gaol profiles show <name>
gaol profiles resolve <name>  # Show dependency order
gaol profiles validate <file.yaml>
```

## CLI Command Reference

### Container Management

#### `create`
Create a new container with optional profiles and configuration.

```bash
gaol create <name> [OPTIONS]

Options:
  -r, --runtime TEXT      Runtime: docker, nspawn, libvirt (default: docker)
  -d, --distro TEXT       Base distro: trixie, bookworm, etc. (default: trixie)
  -i, --image TEXT        Custom base image (overrides distro)
  -p, --profile TEXT      Profile(s) to apply (can repeat)
  -P, --port TEXT         Port mapping: host:container (can repeat)
  -v, --volume TEXT       Volume mount: host:container[:ro] (can repeat)
  -e, --env TEXT          Environment variable: KEY=VALUE (can repeat)
  -n, --network TEXT      Network mode: shared, bridged, host, none
  --privileged            Run in privileged mode
  --gpu                   Enable GPU passthrough
  --gpu-device INT        Specific GPU device ID(s)
  --gpu-vendor TEXT       GPU vendor: nvidia, amd, intel, auto
  --device TEXT           Device passthrough path
  -f, --file TEXT         Spec file to use as base
  -s, --start             Start after creation
```

Examples:
```bash
# Basic container
gaol create myapp --runtime docker --distro trixie

# Development environment with profiles
gaol create dev --profile base --profile dev-python --start

# Web server with ports and volumes
gaol create web -p 8080:80 -v ./html:/var/www/html --start

# GPU-enabled container
gaol create ml --gpu --profile dev-python --start

# From spec file with overrides
gaol create myapp -f base.yaml -p 9000:80 --start
```

#### `exec`
Execute a command in a running container.

```bash
gaol exec <name> [OPTIONS] -- <command>

Options:
  -u, --user TEXT      User to run as
  -w, --workdir TEXT   Working directory
```

Examples:
```bash
gaol exec myapp -- ls -la /app
gaol exec myapp -u root -- apt update
gaol exec myapp -w /workspace -- python script.py
```

#### `shell`
Open an interactive shell in a container.

```bash
gaol shell <name> [--user TEXT]
```

#### `cp`
Copy files between host and container.

```bash
gaol cp <src> <dest>

# Host to container
gaol cp ./local/file.txt mycontainer:/path/in/container

# Container to host
gaol cp mycontainer:/path/file.txt ./local/
```

#### `list`
List containers across runtimes.

```bash
gaol list [OPTIONS]

Options:
  --all-runtimes    Show containers from all runtimes
  -r, --runtime     Filter by specific runtime
```

#### `status`
Get detailed status of a container.

```bash
gaol status <name> [--runtime TEXT]
```

#### `stats`
Display real-time resource usage statistics.

```bash
gaol stats <name> [--runtime TEXT]
```

Output includes: CPU %, memory usage, network I/O, disk I/O, process count.

#### `inspect`
Show stored container configuration.

```bash
gaol inspect <name>
```

#### `logs`
View container logs.

```bash
gaol logs <name> [OPTIONS]

Options:
  -f, --follow      Stream logs in real-time
  --tail INT        Number of lines to show
  --since TEXT      Show logs since timestamp
```

### Snapshots

```bash
# Create a snapshot
gaol snapshot create <container> <snapshot-name>

# List snapshots
gaol snapshot list <container>

# Restore from snapshot
gaol snapshot restore <container> <snapshot-name>

# Delete snapshot
gaol snapshot delete <container> <snapshot-name>
```

### Migration

Move containers between runtimes.

```bash
gaol migrate <container> --to <runtime> [OPTIONS]

Options:
  --dry-run              Preview changes without migrating
  --no-preserve-source   Delete source after migration
  --force                Force migration even with warnings
  -v, --verbose          Show detailed progress
```

Examples:
```bash
# Docker to nspawn
gaol migrate myapp --to nspawn

# Preview migration to libvirt
gaol migrate myapp --to libvirt --dry-run
```

### GPU Management

```bash
# List available GPUs
gaol gpu list [--vendor nvidia|amd|intel] [--json]

# Show GPU details
gaol gpu info <device-id>

# Check driver/runtime support
gaol gpu check
```

### Secrets

```bash
# Initialize secrets (creates master key)
gaol secret init

# Create a secret
gaol secret create <name>

# List secrets
gaol secret list

# Show secret value
gaol secret show <name>

# Delete secret
gaol secret delete <name>
```

Use secrets in specs with `${secret:NAME}` syntax:
```yaml
environment:
  DATABASE_URL: "postgres://user:${secret:DB_PASS}@localhost/db"
```

### Container Groups

Pod-like orchestration for related containers.

```bash
# Start a group
gaol group up <group.yaml>

# Group status
gaol group status <name>

# Execute in group container
gaol group exec <group> <container> -- <command>

# View logs
gaol group logs <group> [--container <name>]

# Stop group
gaol group down <name>
```

### Dev Tunnels

Expose containers to the internet via cloudflared.

```bash
# Start tunnel
gaol tunnel start <container> <port>

# List active tunnels
gaol tunnel list

# Stop tunnel
gaol tunnel stop <tunnel-id>

# Stop all tunnels for container
gaol tunnel stop-all [--container <name>]
```

### Desktop Integration

Create desktop entries for GUI apps in containers.

```bash
# Create desktop entry
gaol desktop create <container> <exec-command> --name "App Name"

# List entries
gaol desktop list

# Run GUI app
gaol desktop run <container> -- <command>

# Uninstall entry
gaol desktop uninstall <container>
```

### Security

```bash
# Initialize Falco security monitoring
gaol security init [--auto-install]

# Check security status
gaol security status

# Stream security events
gaol security events [--follow] [--container <name>]

# Generate security policies
gaol security policy generate <container> --type seccomp|apparmor
```

## Spec File Format

Container specs use YAML format. Create with `gaol spec init <name>`.

### Complete Spec Reference

```yaml
# Container name (required)
name: mycontainer

# Runtime: docker, nspawn, libvirt
runtime: docker

# Base distribution
distro: trixie

# Or custom image (overrides distro)
image: debian:bookworm-slim

# Profiles to apply (in order)
profiles:
  - base
  - dev-python

# Resource limits
resources:
  memory: 4G        # Memory limit
  cpus: 2           # CPU count
  cpu_shares: 1024  # Relative CPU weight
  disk: 20G         # Disk quota

# Network configuration
network:
  mode: shared      # shared, bridged, host, none
  hostname: myhost
  ports:
    - 8080:80       # host:container
    - 8443:443/tcp  # with protocol
  dns:
    - 1.1.1.1
    - 8.8.8.8

# Volume mounts
volumes:
  - /host/path:/container/path
  - ~/config:/app/config:ro  # read-only

# Environment variables
environment:
  NODE_ENV: production
  DEBUG: "false"
  API_KEY: "${secret:MY_API_KEY}"  # from secrets

# Working directory
working_dir: /app

# Default command
command: ["node", "server.js"]

# Security options
privileged: false
read_only: false

# GPU configuration
gpu:
  enabled: true
  vendor: nvidia    # nvidia, amd, intel, auto
  device_ids: [0]   # specific GPUs or empty for all
  capabilities:
    - compute
    - utility

# Device passthrough
devices:
  - /dev/dri/card0
```

### Minimal Spec

```yaml
name: simple
runtime: docker
profiles:
  - base
```

## Profile Format

Profiles define reusable container configurations. Place custom profiles in:
- `~/.config/gaol/profiles/`
- `./profiles/` (project-local)

### Profile Reference

```yaml
name: my-profile
description: My custom profile
version: "1.0.0"

# Dependencies (applied first)
depends_on:
  - base
  - name: gui
    optional: true

# Conflicts
conflicts_with:
  - conflicting-profile

# Requirements
requires_root: false
requires_privileged: false
supported_distros:
  - trixie
  - bookworm

# Packages to install
packages:
  - python3
  - python3-pip
  - git

# Additional repositories
package_repos:
  - deb http://example.com/repo stable main

# Services to enable
services:
  - nginx
  - postgresql

# Setup commands (run after packages)
setup_commands:
  - pip install poetry
  - poetry config virtualenvs.in-project true

# Files to create
files:
  /etc/myapp/config.yaml: |
    setting: value

# Environment variables
environment:
  MY_VAR: value

# Ports to expose
exposed_ports:
  - 8080
  - 443

# Volume mounts
volumes:
  /data: /app/data

# Capabilities
capabilities_add:
  - NET_ADMIN
capabilities_drop:
  - SYS_ADMIN
```

### Built-in Profiles

| Profile | Description |
|---------|-------------|
| `base` | Essential tools (curl, wget, vim, git) |
| `dev-python` | Python with uv, ruff, pytest |
| `dev-node` | Node.js with pnpm, prettier |
| `gui` | X11/Wayland forwarding |
| `vnc` | TigerVNC server |
| `rdp` | xrdp server |
| `sunshine` | Game streaming server |
| `rustdesk` | Remote desktop |
| `tailscale` | Tailscale VPN |
| `tor` | Tor routing |

## Common Workflows

### 1. Development Environment Setup

```bash
# Create a Python dev environment
gaol create dev \
  --profile base \
  --profile dev-python \
  -v ~/projects:/workspace \
  -p 8000:8000 \
  --start

# Enter the container
gaol shell dev

# Or execute directly
gaol exec dev -- python -m pytest
```

### 2. Web Application Deployment

```bash
# Create spec file
cat > webapp.yaml << 'EOF'
name: webapp
runtime: docker
profiles:
  - base
network:
  ports:
    - 80:80
    - 443:443
volumes:
  - ./app:/var/www/html:ro
environment:
  NODE_ENV: production
EOF

# Deploy
gaol apply webapp.yaml --start

# Check status
gaol status webapp
gaol logs webapp --follow
```

### 3. GPU-Enabled ML Container

```bash
# Check GPU availability
gaol gpu list
gaol gpu check

# Create ML container
gaol create ml-dev \
  --gpu \
  --profile dev-python \
  -v ~/ml-projects:/workspace \
  --start

# Verify GPU access
gaol exec ml-dev -- nvidia-smi
```

### 4. Container Groups (Microservices)

```yaml
# stack.yaml
name: web-stack
shared_network: true

containers:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: "${secret:DB_PASS}"
    healthcheck:
      type: tcp
      port: 5432

  api:
    profiles: [base, dev-python]
    depends_on: [db]
    ports: ["8000:8000"]
    volumes:
      - ./api:/app

  web:
    image: nginx:alpine
    depends_on: [api]
    ports: ["80:80"]
```

```bash
gaol group up stack.yaml
gaol group status web-stack
gaol group logs web-stack --container api
gaol group down web-stack
```

### 5. Snapshot and Restore

```bash
# Create snapshot before changes
gaol snapshot create myapp pre-update

# Make changes...
gaol exec myapp -- apt upgrade -y

# If something breaks, restore
gaol snapshot restore myapp pre-update
```

### 6. Runtime Migration

```bash
# Start with Docker for development
gaol create myapp --runtime docker --profile base --start

# Migrate to nspawn for production (lighter weight)
gaol migrate myapp --to nspawn

# Or migrate to libvirt for full isolation
gaol migrate myapp --to libvirt
```

### 7. Expose Container Publicly

```bash
# Start container with web server
gaol create demo -p 8080:80 --start

# Create public tunnel
gaol tunnel start demo 8080
# Returns: https://random-name.trycloudflare.com

# Stop when done
gaol tunnel stop-all --container demo
```

## Error Handling

### Common Errors and Solutions

| Error | Cause | Solution |
|-------|-------|----------|
| "Runtime not available" | Runtime not installed | Install docker/nspawn/libvirt |
| "Container not found" | Wrong name or runtime | Use `gaol list --all-runtimes` |
| "Port already in use" | Port conflict | Change port mapping or stop conflicting service |
| "Permission denied" | Need root for nspawn | Run with sudo or use Docker |
| "GPU not found" | No GPU or drivers missing | Run `gaol gpu check` |
| "Secret not found" | Secret doesn't exist | Create with `gaol secret create` |
| "Profile not found" | Typo or missing profile | Check `gaol profiles list` |

### Debugging Tips

```bash
# Check container status
gaol status <name>

# View logs
gaol logs <name> --tail 100

# Check resource usage
gaol stats <name>

# Inspect stored config
gaol inspect <name>

# Verify runtime availability
gaol runtimes
```

## Best Practices for Agents

### 1. Always Check Before Acting

```bash
# Before creating, check if container exists
gaol list | grep mycontainer

# Before starting, check status
gaol status mycontainer

# Before using GPU, verify availability
gaol gpu check
```

### 2. Use Specs for Reproducibility

```bash
# Export existing container to spec
gaol spec export mycontainer -o container.yaml

# Apply spec (idempotent)
gaol apply container.yaml
```

### 3. Handle Failures Gracefully

```bash
# Use snapshots before destructive operations
gaol snapshot create myapp backup

# Check command exit codes
gaol exec myapp -- command || echo "Command failed"

# Force cleanup if needed
gaol destroy myapp --force
```

### 4. Use Appropriate Runtimes

| Use Case | Recommended Runtime |
|----------|---------------------|
| Development | Docker |
| Production (lightweight) | nspawn |
| Untrusted workloads | libvirt |
| GUI applications | Docker or nspawn with gui profile |
| GPU workloads | Docker (best nvidia support) |

### 5. Resource Management

```bash
# Monitor resource usage
gaol stats myapp

# Set limits in spec
resources:
  memory: 2G
  cpus: 2
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `GAOL_RUNTIME` | Default runtime |
| `GAOL_DISTRO` | Default distribution |
| `GAOL_MASTER_KEY` | Secrets master key (if not using keyring) |
| `GAOL_CONFIG_DIR` | Config directory (default: ~/.config/gaol) |

## File Locations

| Path | Purpose |
|------|---------|
| `~/.config/gaol/` | Configuration directory |
| `~/.config/gaol/config.yaml` | Global settings |
| `~/.config/gaol/containers/` | Stored container configs |
| `~/.config/gaol/profiles/` | Custom profiles |
| `~/.config/gaol/secrets/` | Encrypted secrets |
| `~/.config/gaol/groups/` | Container group definitions |
| `~/.config/gaol/tunnels/` | Active tunnel state |

## Integration Patterns

### Running Tests in Container

```bash
# Create test environment
gaol create test-env --profile dev-python -v .:/app --start

# Run tests
gaol exec test-env -w /app -- pytest tests/

# Cleanup
gaol destroy test-env
```

### Building and Deploying

```bash
# Build in container
gaol exec build-env -- make build

# Copy artifacts out
gaol cp build-env:/app/dist ./dist

# Deploy to production container
gaol cp ./dist prod-env:/app/dist
gaol exec prod-env -- systemctl restart app
```

### Database Operations

```bash
# Create database container
gaol create postgres --image postgres:16 \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  --start

# Run migrations
gaol exec app -- python manage.py migrate

# Backup database
gaol exec postgres -- pg_dump mydb > backup.sql
```

## Version Information

Check gaol version:
```bash
gaol --version
```

This documentation covers gaol's full feature set. For the latest updates, refer to the project's `plan.md` and source code.
