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.

2.8: 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.9: Agent Documentation

Create docs/agents/{agent}.md following this structure (see docs/agents/codex.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.10: Update Project README

Edit README.md:

• Add row to the "Supported agents" table with the agent name, project URL, and status columns (CLI, VS Code, JetBrains). New agents are typically :large_blue_circle: Preview for CLI and devcontainer modes.
• 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: go test ./...
   • 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)
• internal/embeddata/templates/compose/base.yml (shared compose base layer with proxy and agent skeleton)
• internal/embeddata/templates/compose/mode.devcontainer.yml (devcontainer mode overlay)
• internal/embeddata/templates/claude/cli/agent.yml (agent compose layer with env vars)
• internal/embeddata/templates/copilot/cli/agent.yml (simplest agent compose layer)
• internal/embeddata/templates/claude/devcontainer/devcontainer.json (devcontainer with extensions and JetBrains plugins)
• internal/embeddata/templates/codex/devcontainer/devcontainer.json (CLI-only agent, no extensions)
• internal/runtime/agents.go (agent registry: supported list and validation)
• internal/scaffold/init.go (CLI and devcontainer init flow entrypoints)
• internal/scaffold/devcontainer.go (devcontainer JSON rendering and merge behavior)
• internal/cli/init_test.go (init command assertions and prompting expectations)
• internal/cli/switch_test.go (switch command assertions and agent validation coverage)
• images/proxy/addons/enforcer.py (service domains, alphabetical ordering)
• images/proxy/render-policy (KNOWN_AGENTS set, policy rendering validation)
• images/build.sh (build functions and case statement)
• docs/agents/codex.md (simplest agent doc, CLI-only)
• docs/agents/copilot.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)