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)