Agent skill

docker-sandbox

Create, manage, and execute agent tools (claude, codex) inside Docker sandboxes for isolated code execution. Use when running agent loops, spawning tool subprocesses, or any task requiring process isolation. Triggers on "sandbox", "isolated execution", "docker sandbox", "safe agent execution", or when working on agent loop infrastructure.

View SKILL.md on GitHub Repository
Stars 51
Forks 3

Install this agent skill to your Project

npx add-skill https://github.com/joelhooks/joelclaw/tree/main/skills/docker-sandbox

SKILL.md

Docker Sandbox for Agent Tools

Isolated execution of claude, codex, and other agent tools using Docker Desktop's docker sandbox (v0.11.0+). Uses existing Claude Max and ChatGPT Pro subscriptions — no API key billing.

ADR: ADR-0023

Prerequisites

  • Docker Desktop running (OrbStack works)
  • docker sandbox version returns ≥0.11.0
  • Auth secrets stored in agent-secrets:
    • claude_setup_token — from claude setup-token (1-year token, Max subscription)
    • codex_auth_json — contents of ~/.codex/auth.json (ChatGPT Pro subscription)

Quick Reference

bash
# Create a sandbox
docker sandbox create --name my-sandbox claude /path/to/project

# Run a command in it
docker sandbox exec -e "CLAUDE_CODE_OAUTH_TOKEN=..." -w /path/to/project my-sandbox \
  claude -p "implement the feature" --output-format text --dangerously-skip-permissions

# List sandboxes
docker sandbox ls

# Remove
docker sandbox rm my-sandbox

Auth Setup (One-Time)

Claude (Max subscription)

Run interactively on the host (needs browser for OAuth):

bash
claude setup-token

This opens a browser, completes OAuth, and prints a token like sk-ant-oat01-.... Valid for 1 year.

Store it:

bash
secrets add claude_setup_token --value "sk-ant-oat01-..."

Use in sandbox:

bash
TOKEN=$(secrets lease claude_setup_token --ttl 1h --raw)
docker sandbox exec -e "CLAUDE_CODE_OAUTH_TOKEN=$TOKEN" my-sandbox claude auth status
# → loggedIn: true, authMethod: oauth_token

Codex (ChatGPT Pro subscription)

Authenticate codex locally (needs browser):

bash
codex  # Select "Sign in with ChatGPT", complete OAuth

The auth file at ~/.codex/auth.json is portable (not host-tied). Store it:

bash
secrets add codex_auth_json --value "$(cat ~/.codex/auth.json)"

Inject into sandbox:

bash
AUTH=$(secrets lease codex_auth_json --ttl 1h --raw)
docker sandbox exec my-sandbox bash -c "mkdir -p ~/.codex && cat > ~/.codex/auth.json << 'EOF'
${AUTH}
EOF"

Token Refresh

Token Lifetime Refresh
claude_setup_token 1 year Run claude setup-token again, update secret
codex_auth_json Until subscription change Re-run codex login if auth fails, update secret

Agent Loop Integration

Pre-warm Pattern

Create sandbox(es) at loop start, reuse for all stories, destroy at loop end.

PLANNER (loop start)
  ├── docker sandbox create --name loop-{loopId}-claude claude {workDir}
  ├── docker sandbox create --name loop-{loopId}-codex codex {workDir}  # if needed
  └── inject auth into both

IMPLEMENTOR / TEST-WRITER / REVIEWER (per story)
  └── docker sandbox exec -w {workDir} -e CLAUDE_CODE_OAUTH_TOKEN=... loop-{loopId}-{tool} \
        {tool command}
      # ~90ms overhead, workspace changes visible on host immediately

COMPLETE / CANCEL (loop end)
  ├── docker sandbox rm loop-{loopId}-claude
  └── docker sandbox rm loop-{loopId}-codex

Timing

Operation Time
Create (cached image) ~14s
Exec (warm sandbox) ~90ms
Stop ~11s
Remove ~150ms

Net overhead per loop: ~14s create + ~90ms × N stories = negligible for loops running 5-10 stories at 5-15min each.

Workspace Mount

The workspace is bidirectional — same path on host and in sandbox:

  • File created in sandbox → visible on host at same path
  • File created on host → visible in sandbox
  • Git operations work normally (host sees sandbox changes, sandbox sees host commits)

Sandbox Templates

Template Tools Included
claude claude 2.1.42, git, node 20, npm
codex codex 0.101.0, git, node 20, npm

Neither includes bun. If bun is needed, use host-mode fallback or install it post-create.

Env Vars

Pass via docker sandbox exec -e:

bash
docker sandbox exec \
  -e "CLAUDE_CODE_OAUTH_TOKEN=$TOKEN" \
  -e "NODE_ENV=development" \
  -w /path/to/project \
  my-sandbox \
  claude -p "prompt" --output-format text --dangerously-skip-permissions

Network Control

Sandboxes have network access by default. Restrict with proxy rules:

bash
# Allow only API endpoints
docker sandbox network proxy my-sandbox --policy deny
docker sandbox network proxy my-sandbox --allow-host api.anthropic.com
docker sandbox network proxy my-sandbox --allow-host api.openai.com

Fallback to Host Mode

If Docker is unavailable:

bash
# Check availability
docker info >/dev/null 2>&1 || echo "Docker not available"

# Force host mode
export AGENT_LOOP_HOST=1

Saving Custom Templates

If you install additional tools in a sandbox, save it as a template:

bash
# Install tools
docker sandbox exec my-sandbox bash -c 'npm i -g @anthropic-ai/claude-code @openai/codex'

# Save as template
docker sandbox save my-sandbox my-agent-template:v1

# Use the template for future sandboxes
docker sandbox create --name fast-sandbox -t my-agent-template:v1 claude /path/to/project

Implementation in utils.ts

New Functions (ADR-0023)

typescript
// Create sandbox for a loop
async function createLoopSandbox(
  loopId: string,
  tool: "claude" | "codex",
  workDir: string
): Promise<string>  // returns sandbox name

// Execute command in existing sandbox
async function execInSandbox(
  sandboxName: string,
  command: string[],
  opts: { env?: Record<string, string>; workDir?: string; timeout?: number }
): Promise<{ exitCode: number; output: string }>

// Destroy loop sandbox(es)
async function destroyLoopSandbox(loopId: string): Promise<void>

Replacing spawnTool()

Current spawnTool() in implement.ts checks AGENT_LOOP_HOST and isDockerAvailable(). Update it to:

  1. Check if sandbox loop-{loopId}-{tool} exists (created by planner)
  2. If yes → execInSandbox() with auth env vars
  3. If no → fall back to spawnToolHost() (current host-mode behavior)

Troubleshooting

"Not logged in" in sandbox

Auth not injected. Check:

bash
docker sandbox exec my-sandbox bash -c 'claude auth status'
docker sandbox exec my-sandbox bash -c 'cat ~/.codex/auth.json | head -3'

Sandbox creation slow

First pull downloads ~500MB image. Subsequent creates use cached image (~14s). Use docker sandbox save to create a pre-configured template.

File not visible between host and sandbox

Only the workspace path is mounted. Files outside the workspace directory are not shared.

"docker sandbox: command not found"

Docker Desktop must be running. Check version: docker sandbox version. Requires Docker Desktop 4.40+ with sandbox extension.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

joelhooks/joelclaw

skill-review

Audit and maintain the joelclaw skill inventory. Use when checking skill health, fixing broken symlinks, finding stale skills, or running the skill garden. Triggers: 'skill audit', 'check skills', 'stale skills', 'skill health', 'skill garden', 'broken skill', 'skill review', 'fix skills', 'garden skills', or any task involving skill inventory maintenance.

51 3
Explore
joelhooks/joelclaw

cli-design

Design and build agent-first CLIs with HATEOAS JSON responses, context-protecting output, and self-documenting command trees. Use when creating new CLI tools, adding commands to existing CLIs (joelclaw, slog), or reviewing CLI design for agent-friendliness. Triggers on 'build a CLI', 'add a command', 'CLI design', 'agent-friendly output', or any task involving command-line tool creation.

51 3
Explore
joelhooks/joelclaw

daily-summary

Generate a daily system activity summary across all joelclaw subsystems. Triggers on 'daily summary', 'what happened today', 'system report', 'today's tally', 'activity summary', 'what did we do', 'daily report'.

51 3
Explore
joelhooks/joelclaw

inngest-durable-functions

Create and configure Inngest durable functions. Covers triggers (events, cron, invoke), step execution and memoization, idempotency, cancellation, error handling, retries, logging, and observability.

51 3
Explore
joelhooks/joelclaw

recall

Fan-out search across all memory sources when context is unclear or vaguely referenced. Triggers on: 'from earlier', 'remember when', 'what we discussed', 'that thing with', 'the conversation about', 'did we ever', 'what happened with', 'you mentioned', 'we talked about', 'earlier today', 'last session', 'the other day', or any vague reference to past context that needs resolution before the agent can act.

51 3
Explore
joelhooks/joelclaw

inngest-local

Set up self-hosted Inngest on macOS as a durable background task manager for AI agents. Interactive Q&A to match intent — from Docker one-liner to full k8s deployment with persistent state. Use when: 'set up inngest', 'background tasks', 'durable workflows', 'self-host inngest', 'event-driven functions', 'cron jobs', or any request for a local workflow engine.

51 3
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results