This file provides guidance to agents working in this repository.

Agent Sandbox is a Go CLI plus Docker images and templates for running AI coding agents inside locked-down local sandboxes.

Stable repo surfaces:

1. cmd/agentbox and internal/ - the Go CLI, runtime detection, scaffolding, and Docker invocation code
2. images/ - the base image, agent images, proxy image, and proxy enforcement tests
3. .agent-sandbox/ - generated runtime files for developing this repo locally
4. README.md and docs/ - user-facing docs, agent setup guides, policy docs, and troubleshooting
5. .github/workflows/ - Go tests, proxy tests, image builds, release binaries, and per-agent version checks

Supported agents in the CLI: claude, codex, gemini, hermes, opencode, pi, copilot, factory.

Repo-wide support is defined by the combination of:

• internal/runtime/agents.go
• images/agents/<agent>/
• internal/embeddata/templates/<agent>/
• docs/agents/<agent>.md
• .github/workflows/check-<agent>-version.yml

Do not infer product support from the checked-in .agent-sandbox/ tree. That directory only reflects which agent layers have been initialized for this repo's local development runtime.

Prefer these in order when describing or changing current behavior:

1. Code in internal/ and images/
2. Tests in internal/**/*_test.go and images/proxy/tests/
3. User-facing docs in README.md, docs/cli.md, docs/policy/schema.md, and docs/agents/*.md

Treat docs/plan/ and docs/roadmap.md as planning or historical context, not as the source of truth for current implementation.

internal/embeddata/templates/ is the source of truth for files generated by agentbox init and agentbox switch.

This repo is usually developed from inside its own sandbox container. Network restrictions are real:

• Outbound traffic from the agent container must go through the proxy sidecar
• Direct outbound is blocked by iptables
• SSH is disabled, and Git remote URLs are rewritten to HTTPS
• Unrestricted git or network operations should be run from the host

Container baseline:

• Debian bookworm
• Non-root dev user (uid/gid 501)
• Zsh with minimal prompt
• GODEBUG=http2client=0 in the compose stack to avoid Go HTTP/2 issues through mitmproxy
• /workspace bind-mounted to the repo
• Per-agent persistent state volumes plus /commandhistory

Build local images with:

./images/build.sh

The script supports base, proxy, every agent name, and all.

Generated runtime files live under .agent-sandbox/.

Key files:

• .agent-sandbox/active-target.env - active agent and related runtime metadata
• .agent-sandbox/compose/base.yml - managed shared compose layer
• .agent-sandbox/compose/agent.<agent>.yml - managed agent-specific compose layer
• .agent-sandbox/compose/user.override.yml - shared user-owned compose overrides
• .agent-sandbox/compose/user.agent.<agent>.override.yml - per-agent user-owned compose overrides
• .agent-sandbox/policy/user.policy.yaml - shared user-owned policy
• .agent-sandbox/policy/user.agent.<agent>.policy.yaml - per-agent user-owned policy

Devcontainer mode also uses:

• .devcontainer/devcontainer.json
• .devcontainer/devcontainer.user.json
• .agent-sandbox/compose/mode.devcontainer.yml
• .agent-sandbox/policy/policy.devcontainer.yaml

Managed files are regenerated. User-owned override and policy files are preserved across switches.

Legacy single-file layouts are no longer supported. If you encounter old docker-compose.yml or policy-*.yaml generated files, follow docs/upgrades/m8-layered-layout.md.

• internal/cli - Cobra commands and user-facing command behavior
• internal/runtime - path discovery, active target state, lifecycle helpers, compose selection, and legacy-layout detection
• internal/scaffold - file generation for init, switch, devcontainer output, and runtime sync
• internal/docker - Docker and Docker Compose invocation helpers plus image lookup logic
• internal/embeddata - embedded template access
• internal/version - version metadata
• internal/testutil - test helpers

Current root commands:

• init
• switch
• edit
• policy
• proxy
• bump
• up
• down
• logs
• compose
• exec
• destroy
• version
• completion

images/base/

• Shared base image
• Startup and firewall scripts such as entrypoint.sh, init-firewall.sh, and install-proxy-ca.sh
• Optional language stack installers under images/base/stacks/

images/agents/

• One directory per supported agent
• Agent-specific Dockerfiles and any agent-specific config files

images/proxy/

• Proxy Dockerfile and entrypoint
• render-policy for policy rendering and merge logic
• addons/enforcer.py for proxy enforcement
• Python unit tests under images/proxy/tests/

Do not confuse template sources with generated runtime files.

• Edit internal/embeddata/templates/ when changing what agentbox init or agentbox switch generates
• Edit the checked-in .agent-sandbox/ tree only when adjusting this repo's local development runtime

Important template groups:

• internal/embeddata/templates/compose/ - shared compose layers and user override scaffolds
• internal/embeddata/templates/<agent>/cli/agent.yml - agent-specific CLI compose template
• internal/embeddata/templates/<agent>/devcontainer/devcontainer.json - agent-specific devcontainer template
• internal/embeddata/templates/policy.yaml and user.policy.yaml - shared policy scaffolds
• internal/embeddata/templates/user.agent.policy.yaml - per-agent user policy scaffold

The stable high-level model is still:

1. Proxy enforcement in the proxy sidecar
2. Firewall enforcement in the agent container

Security-critical files:

• images/base/init-firewall.sh
• images/base/entrypoint.sh
• images/base/install-proxy-ca.sh
• images/proxy/addons/enforcer.py
• images/proxy/render-policy

Policy docs and examples live under:

• docs/policy/schema.md
• docs/policy/examples/all-agents.yaml

For one-off policy changes in a project sandbox, prefer the user-owned files under .agent-sandbox/policy/ over changing proxy code.

Primary test commands:

go test ./...
/opt/proxy-python/bin/python3 -m unittest discover -s images/proxy/tests -p 'test_*.py'

Use /opt/proxy-python/bin/python3 for proxy Python tests. It is the dev-image venv with mitmproxy, pytest, and PyYAML; system Python does not have all proxy test dependencies.

Useful local verification steps:

./images/build.sh proxy
agentbox policy config
agentbox compose restart proxy
agentbox compose logs proxy

To sanity-check proxy enforcement inside a running sandbox:

curl -x http://proxy:8080 https://example.com
curl -x http://proxy:8080 https://github.com

The first request should be blocked. The second should succeed only if the active policy allows GitHub.

Key workflows:

• .github/workflows/go-tests.yml - runs Go tests with coverage and builds the CLI
• .github/workflows/proxy-tests.yml - runs the proxy Python test suite
• .github/workflows/build-images.yml - builds and publishes the base, proxy, and all agent images
• .github/workflows/release-go-binaries.yml - builds release archives for tagged Go CLI releases

Per-agent version check workflows exist for:

• claude
• codex
• copilot
• factory
• gemini
• hermes
• opencode
• pi

1. Open a PR that moves the [Unreleased] entries in CHANGELOG.md under ## [X.Y.Z] - YYYY-MM-DD with a one-line summary, keeps an empty [Unreleased] section on top, and bumps the --version vX.Y.Z examples in README.md and scripts/install-agentbox.sh.
2. After it merges, push a lightweight tag vX.Y.Z on the merge commit. release-go-binaries.yml builds the archives and opens a draft GitHub release with generated notes.
3. The maintainer publishes the draft and edits the notes. Publishing is outside the sandbox proxy's write allowlist, so an agent stops after reporting the draft release URL.

build-images.yml runs on pushes to main that touch images/ and on release events. A fix merged after a release's image build reaches users through the next push-triggered build and agentbox bump.

• Open agent-authored PRs as drafts with gh api -X POST repos/{owner}/{repo}/pulls -F draft=true. The gh pr commands are blocked in the sandbox; see docs/github.md.
• PRs are rebase-merged. A PR stacked on another branch needs git rebase origin/main after its base lands, which requires a force-push of the PR branch. Ask the maintainer before any force-push and use --force-with-lease.
• Never amend a pushed commit. Address review feedback in new commits.
• Every PR gets an automated Greptile review. Evaluate each comment, fix the valid ones in a new commit, and reply on the thread with the commit and the test that covers it. Then post a PR comment containing @greptile review so the new commit gets a fresh review.

Use the add-agent skill or follow an existing agent end to end.

A complete new-agent change usually touches all of these:

• internal/runtime/agents.go
• images/agents/<name>/Dockerfile
• internal/embeddata/templates/<name>/cli/agent.yml
• internal/embeddata/templates/<name>/devcontainer/devcontainer.json
• docs/agents/<name>.md
• images/build.sh
• .github/workflows/check-<name>-version.yml
• .github/workflows/build-images.yml
• images/proxy/render-policy
• images/proxy/addons/enforcer.py
• README.md if the support matrix changes

Relevant docs:

• docs/git.md - git credentials, SSH-to-HTTPS rewriting, and worktree caveats
• docs/github.md - repo-scoped GitHub API access through gh api, token permissions, and the write allowlist
• docs/dotfiles.md - dotfiles and shell customization
• docs/stacks/ - optional language stacks
• docs/images.md - image pinning and bump workflow
• docs/troubleshooting.md - common issues and fixes

Primary target: Colima on Apple Silicon.

CI builds images for both linux/amd64 and linux/arm64, so avoid changes that silently assume only one architecture.