Hermes + Gondolin (macOS Apple Silicon)

Architecture
  macOS (Apple Silicon)
    -> Colima VM (Linux, VZ framework, nested virtualization)
      -> Docker container (python:3.11-alpine + QEMU + Gondolin)
        -> Gondolin micro-VM
          -> Hermes runs here
        <- Gondolin HTTP proxy injects secrets only for allowed API hosts

Secret Handling
  Secrets are configured in secrets/provider.env using paired lines:

    SECRET_<NAME>=<api-key>
    HOSTS_<NAME>=<comma-separated hostnames>

  Example:
    SECRET_OPENAI_API_KEY=sk-...
    HOSTS_OPENAI_API_KEY=api.openai.com

  - SECRET_ keys are passed via --host-secret to Gondolin
  - The agent never sees the real key; Gondolin's proxy injects it
    only for HTTP requests to the matching HOSTS_ destinations
  - Non-SECRET_ lines are passed as plain --env vars (do NOT put
    secrets in these; they are visible inside the VM)

Network Access
  By default, the Gondolin VM can only reach hosts listed in HOSTS_ entries.
  To allow additional outbound HTTP/HTTPS traffic, add an ALLOW_HOSTS line
  to secrets/provider.env:

    ALLOW_HOSTS=github.com,*.github.com,pypi.org

  - Comma-separated list of hostnames or patterns
  - Wildcard patterns supported (e.g. *.example.com matches sub.example.com)
  - HOSTS_ entries are automatically allowed (no need to repeat them)
  - Use ALLOW_HOSTS=* to allow all outbound traffic

GitHub Integration
  To use git or the gh CLI with private repos, add a GitHub PAT to
  secrets/provider.env:

    SECRET_GITHUB_TOKEN=ghp_...
    HOSTS_GITHUB_TOKEN=github.com,api.github.com

  Use GITHUB_TOKEN as the name so Gondolin creates a GITHUB_TOKEN env var
  inside the VM, which gh CLI reads automatically. Gondolin's proxy injects
  the real token into HTTP requests to those hosts.

Auto-Approve
  By default, Hermes prompts for confirmation before running dangerous commands
  (rm -rf, chmod 777, curl|sh, etc.). Since Gondolin already sandboxes execution
  inside a micro-VM, these prompts are often redundant.

  To skip approval prompts, add to secrets/provider.env:

    AUTO_APPROVE=true

  When set, HERMES_INTERACTIVE is not passed into the VM, so Hermes skips
  its dangerous-command approval prompts.

Prerequisites
  brew install colima docker

Quick Start
  1) Add your API key(s) to secrets/provider.env
  2) make up

Commands
  make up                   - init + build + launch Hermes (first run)
  make shell                - launch Hermes (skips build if image exists)
  make shell <session-id>   - resume a previous session
  make run <hermes-cmd>     - run a hermes subcommand (e.g., make run sessions list)
  make build                - rebuild the Docker image
  make status               - show Colima/Docker status
  make down                 - stop Colima profile
  make restart              - restart Colima profile
  make clean                - remove Docker image
  make nuke                 - delete Colima profile (destructive)

Workspace
  workspace/ on the host is mounted at /workspace inside the VM.
  Files created by the agent persist here across sessions.
  Session state (SQLite DB) is also stored in workspace/.

Directory Layout
  secrets/provider.env      - API keys (gitignored, 0600)
  config/config.yaml        - Hermes config (generated by init)
  workspace/                - persistent agent working directory
  workspace/sessions/       - session metadata
  workspace/state.db        - session SQLite database