AI Agent Sandbox

A minimal sandbox for running the opencode AI agent inside a Docker container with a read-only mount of your host repo and a writable workspace inside the container. The run-agent.sh helper wraps Docker Compose to start/stop the container, open a shell, sync changes back to the host, and run opencode inside the container.

Requirements

• Docker with Compose v2 available as docker compose
• Optional network access: choose --network bridge when starting if you need outbound internet (default is none)

Repository Map

• run-agent.sh — CLI to manage the agent lifecycle (start, shell, diff, sync, opencode, stop, reset, list)
• docker-compose.yml — base compose file for the agent container and volumes
• docker-compose.sync.yml — temporary override to remount the host repo read-write during sync
• agent/Dockerfile — dockerd-in-docker image plus opencode install
• agent/entrypoint.sh — starts dockerd, initializes /workspace from /src, installs opencode config/auth if present
• opencode/opencode.json — sample opencode permission defaults

Quickstart

1. Start the agent container (read-only host mount by default):

   ./run-agent.sh start <project-name> <project-dir> [--network none|bridge]

2. Open a shell inside the running agent:

   ./run-agent.sh shell <project-name>

3. Install opencode inside the container (once per agent) and run it:

   ./run-agent.sh install-opencode <project-name>
   ./run-agent.sh opencode <project-name> [args]

Working in the Agent

• Host repo is mounted read-only at /src; your writable workspace is /workspace.
• On first start, /workspace is initialized from /src.
• Changes in /workspace persist across container restarts via the agent-workspace volume.
• Check status/diffs inside the container:

  ./run-agent.sh diff <project-name>

Sync Changes Back to Host

• Use sync to copy tracked/untracked (non-ignored) files from /workspace back to the host repo:

  ./run-agent.sh sync <project-name>

• The sync command confirms with the project name and respects .gitignore by using git ls-files.
• After syncing, commit on the host as usual.

Stop, Reset, List

• Stop container (keeps volumes):

  ./run-agent.sh stop <project-name>

• Reset (deletes container and volumes; requires confirmation):

  ./run-agent.sh reset <project-name>

• List known projects and status:

  ./run-agent.sh list

Day-in-the-Life Workflow

1. ./run-agent.sh start myproj /path/to/repo --network bridge
2. ./run-agent.sh shell myproj and work under /workspace
3. Run ./run-agent.sh opencode myproj [args] for in-container opencode
4. Inspect changes: ./run-agent.sh diff myproj
5. Sync to host: ./run-agent.sh sync myproj
6. On host, review and commit

Troubleshooting

• Ensure docker compose v2 is installed and accessible.
• If dockerd inside the container is slow to start, rerun ./run-agent.sh shell <project-name> and check /tmp/dockerd.log inside the container.
• Need internet inside the container? Start with --network bridge.