add-agent

name	add-agent
description	Add a new AI coding agent to Agent Sandbox. Creates all required files (Dockerfile, templates, CI, docs) and wires the agent into the CLI, proxy, and build system.

Scaffold Agent Support

This skill generates all the files needed to add a new AI coding agent to Agent Sandbox. It follows the established patterns from Claude, Copilot, and Codex implementations.

Arguments

The skill takes a single argument: the agent name (lowercase, no spaces). Example: gemini, opencode, factory.

Process

Step 1: Gather Information

Ask the user for the following (skip any already provided):

1. Agent name (from argument)
2. Display name - human-readable name for comments and labels (e.g., "Google Gemini CLI")
3. Project URL - link to the agent's GitHub repo or website (for README table)
4. Installation method - how to install the agent binary/CLI
   • npm package (like Claude and Copilot)
   • direct binary download from GitHub releases (like Codex)
   • curl installer script
   • pip package
   • go install
5. Package identifier - npm package name, GitHub releases URL pattern, pip package, go module, or download URL
6. Version detection source - how CI detects new releases
   • npm registry (Claude, Copilot): npm view {package} version
   • GitHub releases API (Codex): gh api repos/{owner}/{repo}/releases/latest --jq .tag_name
   • Note any tag prefix that needs stripping (e.g., Codex uses rust-v prefix)
7. Version variable name - env var for build.sh (e.g., GEMINI_VERSION)
8. Config directory - where the agent stores its config in the container (e.g., /home/dev/.gemini)
9. Default config files - any config files to bake into the image (e.g., Codex bakes config.toml to disable its internal sandbox)
10. Internal sandbox - does the agent have its own sandboxing (Landlock, seccomp, etc.) that should be disabled inside our container? If so, how to disable it.
11. Required API domains - domains the agent needs to reach (API, auth/OAuth, CDN)
12. Authentication method - how users authenticate (API key env var, OAuth flow, device code, etc.)
13. Auto-approve flag - the CLI flag for unattended/yolo mode (e.g., --dangerously-skip-permissions, --yolo, --full-auto)
14. VS Code extension ID - if one exists (e.g., github.copilot-chat), or "none" for CLI-only agents
15. Agent-specific environment variables - any env vars the agent needs at runtime
16. Does the agent need Node.js? - whether to install Node.js in the Dockerfile (only if the base image doesn't include it and the agent needs it)

Step 2: Create Files

Generate all files listed below. Read the reference files first to match the exact format and structure.

2.1: Dockerfile

Create images/agents/{agent}/Dockerfile.

Pattern:

• ARG BASE_IMAGE=agent-sandbox-base:local + FROM ${BASE_IMAGE}
• Optional extra packages block (same pattern as existing agents)
• Install Node.js if needed (copy pattern from Copilot Dockerfile)
• As root: create config directory and ~/.local/bin if installing a binary there
• Copy any default config files (e.g., COPY config.toml /home/dev/.{agent}/config.toml)
• USER dev
• Set ENV PATH="/home/dev/.local/bin:$PATH" if installing to ~/.local/bin
• Install the agent (method depends on installation type)
• For direct binary downloads: use ARG TARGETARCH for multi-arch, prefer musl (statically linked) over gnu variants
• Add labels: org.opencontainers.image.description and version label

If the agent needs default config files, create them alongside the Dockerfile (e.g., images/agents/{agent}/config.toml).

2.2: CLI Compose Template

Create cli/templates/{agent}/cli/docker-compose.yml.

Copy from an existing CLI template (Copilot is simplest) and modify:

• Comment at top: # {Display Name} Sandbox
• Agent image: ghcr.io/mattolson/agent-sandbox-{agent}:latest
• State volume: {agent}-state mounted at config directory
• History volume: {agent}-history
• Agent-specific environment variables
• Always include GODEBUG=http2client=0 (workaround for Go programs through mitmproxy)
• Always include HTTP_PROXY, HTTPS_PROXY, NO_PROXY settings
• Update the named volumes section at the bottom

2.3: Devcontainer Compose Template

Create cli/templates/{agent}/devcontainer/docker-compose.yml.

Same as CLI template but add the devcontainer directory mount:

- .:/workspace/.devcontainer:ro

2.4: devcontainer.json

Create cli/templates/{agent}/devcontainer/devcontainer.json.

Copy from existing and modify:

• name: "{Display Name} Sandbox"
• VS Code extensions array if applicable, or remove extensions arrays for CLI-only agents
• Keep proxy settings and JetBrains settings unchanged

2.5: Update CLI Agent List

Edit cli/libexec/init/init: add the new agent name to the available_agents array.

2.6: Update BATS Test

Edit cli/test/init/init.bats: update the "rejects invalid --agent value" test assertion to include the new agent name in the expected agent list string (e.g., "claude copilot codex gemini").

2.7: Update Proxy Service Domains

Edit images/proxy/addons/enforcer.py: add a new entry to SERVICE_DOMAINS dict.

Guidelines:

• Place alphabetically among existing entries
• Prefer wildcards over listing subdomains individually (e.g., *.openai.com covers api.openai.com, auth.openai.com, regional endpoints)
• Only use separate entries for different TLDs (e.g., chatgpt.com is separate from openai.com)
• Include both API domains and auth/OAuth domains so authentication works through the proxy

2.8: Update composefile.bash (if needed)

If the agent has host-side config that users might want to mount into the container (like Claude's ~/.claude/CLAUDE.md and settings.json), add a conditional block in cli/lib/composefile.bash following the pattern of add_claude_config_volumes. This involves:

• Adding an AGENTBOX_MOUNT_{AGENT}_CONFIG env var check in customize_compose_file()
• Creating an add_{agent}_config_volumes() function
• Calling it conditionally when the agent matches

Skip this for agents that don't have meaningful host-side config to mount.

2.9: Update build.sh

Edit images/build.sh to add:

• Default env var at top (e.g., : "${GEMINI_VERSION:=latest}")
• Extra packages env var (e.g., : "${GEMINI_EXTRA_PACKAGES:=}")
• build_{agent}() function following the pattern of existing agent build functions
• Add to the case statement (both specific target and all target)
• Update usage text (first line and examples)

2.10: Agent Documentation

Create docs/{agent}/README.md following this structure (see docs/copilot/README.md or docs/codex/README.md for exact format):

1. Header: # {Display Name} Sandbox Template
2. One-liner: "Run {display name} in a network-locked container..."
3. Link: "See the main README for installation, architecture overview, and configuration options."
4. Setup section: Auth instructions covering all supported auth methods. Note any gotchas (e.g., account-level settings that must be enabled).
5. Usage section: How to start the agent, including the auto-approve flag. Include agentbox compose down for stopping.
6. Required Network Policy section: Show the services: YAML snippet with the agent's service name.

2.11: Update Project README

Edit README.md:

• Add row to the "Supported agents" table with the agent name, project URL, and status (usually Preview for new agents)
• Add link to docs/{agent}/README.md in the "Agent-specific setup" section

Step 3: CI/CD Workflows

Create the CI files directly in .github/workflows/. They follow a clear pattern and can be written without drafting.

3.1: Build Job

Edit .github/workflows/build-images.yml:

• Add {AGENT}_IMAGE_NAME env var (e.g., GEMINI_IMAGE_NAME)
• Add build-{agent} job following the pattern of build-codex (for GitHub releases) or build-copilot (for npm)
• Version detection depends on the source:
  • npm: npm view {package} version
  • GitHub releases: gh api repos/{owner}/{repo}/releases/latest --jq .tag_name with any tag prefix stripping via sed
• Add to summary job needs array
• Add agent version and digest to summary output table

3.2: Version Check Workflow

Create .github/workflows/check-{agent}-version.yml following the pattern of existing version check workflows.

• Pick the next available daily cron slot (current: Claude 6am UTC, Copilot 7am, Codex 8am)
• Match the version source to the build job (npm or GitHub releases)
• Tag prefix: {agent}- for the GHCR tag check
• Trigger build-images.yml if the version tag doesn't exist in GHCR

Step 4: Verify

After creating all files:

1. List all files created/modified
2. Note any manual steps needed
3. Remind user to:
   • Build and test locally: ./images/build.sh {agent}
   • Verify the binary works: docker run --rm agent-sandbox-{agent}:local {agent} --version
   • Test init flow: agentbox init --agent {agent} --mode cli --path /tmp/test-project
   • Run CLI tests: cli/run-tests.bash
   • Test proxy enforcement after starting containers:
     • Allowed domain returns 200: curl -x http://proxy:8080 https://{api-domain}
     • Blocked domain returns 403: curl -x http://proxy:8080 https://example.com
   • Test auth flow inside the container

Reference Files

When generating files, read these for the exact patterns:

• images/agents/claude/Dockerfile (npm install pattern)
• images/agents/copilot/Dockerfile (npm install with Node.js pattern)
• images/agents/codex/Dockerfile (direct binary download pattern, multi-arch, config file baking)
• images/agents/codex/config.toml (baked config file example)
• cli/templates/copilot/cli/docker-compose.yml (simplest CLI template)
• cli/templates/codex/cli/docker-compose.yml (CLI template with agent-specific env vars)
• cli/templates/copilot/devcontainer/docker-compose.yml
• cli/templates/copilot/devcontainer/devcontainer.json
• cli/templates/codex/devcontainer/devcontainer.json (CLI-only agent, no extensions)
• cli/libexec/init/init (agent list)
• cli/test/init/init.bats (test assertion for agent list)
• images/proxy/addons/enforcer.py (service domains, alphabetical ordering)
• images/build.sh (build functions and case statement)
• docs/codex/README.md (simplest agent doc, CLI-only)
• docs/copilot/README.md (agent doc with IDE notes)
• README.md (supported agents table and setup links)
• .github/workflows/build-images.yml (build jobs)
• .github/workflows/check-codex-version.yml (GitHub releases version check)
• .github/workflows/check-copilot-version.yml (npm version check)