Add Agent

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. JetBrains plugin ID - if one exists (e.g., com.anthropic.code.plugin), or "none"
16. Agent-specific environment variables - any env vars the agent needs at runtime
17. 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: Agent Compose Layer

Create internal/embeddata/templates/{agent}/cli/agent.yml.

This is a compose overlay that layers on top of the shared internal/embeddata/templates/compose/base.yml. It contains only agent-specific configuration. Read an existing agent.yml for the exact format.

Contents:

• Managed-by comment header
• services.proxy.volumes: [] (required placeholder for compose merge)
• services.agent.image - the GHCR image reference
• services.agent.volumes - agent-specific state and history volumes
• services.agent.environment - agent-specific env vars (if any)
• Named volume declarations at the bottom

Do NOT include proxy config, HTTP_PROXY, HTTPS_PROXY, capabilities, or other shared settings. Those live in base.yml.

2.3: devcontainer.json

Create internal/embeddata/templates/{agent}/devcontainer/devcontainer.json.

This file references a layered array of compose files. Read an existing devcontainer.json for the exact format.

Key points:

• dockerComposeFile is an array of 5 paths pointing into .agent-sandbox/compose/: base.yml, agent.{name}.yml, mode.devcontainer.yml, user.override.yml, user.agent.{name}.override.yml
• service: "agent"
• workspaceFolder: "/workspace"
• VS Code settings section with port forwarding disabled and security settings
• VS Code extensions array if applicable, or omit for CLI-only agents
• JetBrains settings section with proxy configuration
• JetBrains plugins array if applicable
• remoteUser: "dev"
• overrideCommand: false

2.4: Update Agent Registry

Edit cli/lib/agent.bash:

• Add the new agent to supported_agents_display() (space-separated string)
• Add the new agent to supported_agents() (printf list)
• Add the new agent to select_agent() (option list)
• Add the new agent to the validate_agent() case statement

2.5: Update CLI Compose Scaffolding

Edit cli/lib/cli-compose.bash:

• If the agent has host-side config that users might want to mount (like Claude's CLAUDE.md and settings.json), add a conditional block in scaffold_cli_agent_override_if_missing() following the Claude pattern. This adds commented-out volume entries to user.agent.{name}.override.yml.
• Skip this for agents without meaningful host-side config.

2.6: Update BATS Tests

Two test files reference the agent list string:

1. Edit cli/test/init/init.bats: update the "rejects invalid --agent value" assertion to include the new agent name.
2. Edit cli/test/switch/switch.bats:
   • Update the "switch rejects invalid --agent value" assertion(s) to include the new agent name.
   • Update the stub select_option call in "switch prompts for agent when --agent is omitted" to include the new agent in the argument list.

Both assertions and the stub match the output of supported_agents_display() / select_agent().

2.7: Update Proxy Service Domains and Known Agents

Two files in the proxy image need updating:

images/proxy/service_catalog.py: add a new entry to the SIMPLE_SERVICE_HOSTS 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

If the service needs rule-level semantics (repo scoping, method narrowing beyond the generic readonly mapping), add a dedicated expander function following the GitHub pattern instead of using SIMPLE_SERVICE_HOSTS.

images/proxy/render-policy: add the new agent name to the KNOWN_AGENTS set. This script renders the effective proxy policy at startup and validates the AGENTBOX_ACTIVE_AGENT env var against this set. If the agent is missing, the proxy will refuse to start with an "Unknown agent" error.