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):

Agent name (from argument)
Display name - human-readable name for comments and labels (e.g., "Google Gemini CLI")
Project URL - link to the agent's GitHub repo or website (for README table)
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
Package identifier - npm package name, GitHub releases URL pattern, pip package, go module, or download URL
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)
Version variable name - env var for build.sh (e.g., GEMINI_VERSION)
Config directory - where the agent stores its config in the container (e.g., /home/dev/.gemini)
Default config files - any config files to bake into the image (e.g., Codex bakes config.toml to disable its internal sandbox)
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.
Required API domains - domains the agent needs to reach (API, auth/OAuth, CDN)
Authentication method - how users authenticate (API key env var, OAuth flow, device code, etc.)
Auto-approve flag - the CLI flag for unattended/yolo mode (e.g., --dangerously-skip-permissions, --yolo, --full-auto)
VS Code extension ID - if one exists (e.g., github.copilot-chat), or "none" for CLI-only agents
Agent-specific environment variables - any env vars the agent needs at runtime
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):

Header: # {Display Name} Sandbox Template
One-liner: "Run {display name} in a network-locked container..."
Link: "See the main README for installation, architecture overview, and configuration options."
Setup section: Auth instructions covering all supported auth methods. Note any gotchas (e.g., account-level settings that must be enabled).
Usage section: How to start the agent, including the auto-approve flag. Include agentbox compose down for stopping.
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:

List all files created/modified
Note any manual steps needed
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)