67f47bea06
Ship a Dockerfile.sandbox, docker-compose.yml, .env.example, and docs so users can run GSD auto mode inside an isolated Docker sandbox (MicroVM) without risk to the host filesystem, SSH keys, or other projects. - Dockerfile.sandbox: Node 22 base, gsd-pi pre-installed, non-root user, port 3000 - docker-compose.yml: workspace volume mount, persistent .gsd state, env_file support - .env.example: template for LLM provider keys and optional tool credentials - docker/README.md: setup guide covering sandbox CLI, Compose, two-terminal workflow, credential injection, and network allowlisting - .dockerignore: project-root ignore file for efficient Docker builds - src/tests/docker-template.test.ts: 13 structural tests verifying all template files Fixes #1544 Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| .env.example | ||
| docker-compose.yml | ||
| Dockerfile.sandbox | ||
| README.md | ||
GSD Docker Sandbox
Run GSD auto mode inside an isolated Docker sandbox so it cannot touch your host filesystem, SSH keys, or other projects.
Prerequisites
- Docker Desktop 4.58+ (macOS or Windows; Linux support is experimental)
- At least one LLM provider API key
Quick Start
Option A: Docker Sandbox CLI (recommended)
Docker Sandboxes provide MicroVM isolation — each sandbox runs in a lightweight VM with its own kernel and private Docker daemon.
# Create a sandbox from the template
docker sandbox create --template ./docker --name gsd-sandbox
# Shell into the sandbox
docker sandbox exec -it gsd-sandbox bash
# Inside the sandbox, run GSD
gsd auto "implement the feature described in issue #42"
Option B: Docker Compose
For environments without Docker Sandbox support, use Compose for container-level isolation:
# 1. Configure API keys
cp docker/.env.example docker/.env
# Edit docker/.env with your keys
# 2. Start the sandbox
docker compose -f docker/docker-compose.yml up -d
# 3. Shell into the container
docker exec -it gsd-sandbox bash
# 4. Run GSD inside the container
gsd auto "implement the feature described in issue #42"
Two-Terminal Workflow
GSD's recommended workflow uses two terminals — one for auto mode, one for interactive discussion:
# Terminal 1: auto mode
docker sandbox exec -it gsd-sandbox bash
gsd auto "your task description"
# Terminal 2: discuss / monitor
docker sandbox exec -it gsd-sandbox bash
gsd discuss
With Docker Compose, replace docker sandbox exec with docker exec.
Credential Injection
Docker Sandbox (automatic)
Docker's proxy layer forwards API keys set in your host shell config (~/.bashrc, ~/.zshrc) into the sandbox automatically. Keys are never stored inside the sandbox.
Docker Compose (manual)
Copy docker/.env.example to docker/.env and fill in your keys. The .env file is gitignored and never committed.
Network Allowlisting
If you restrict outbound network access in your sandbox, GSD needs these endpoints:
| Purpose | Endpoints |
|---|---|
| LLM APIs | api.anthropic.com, api.openai.com, generativelanguage.googleapis.com, openrouter.ai |
| Package registry | registry.npmjs.org |
| Research tools | api.search.brave.com, api.tavily.com, r.jina.ai |
| GitHub | api.github.com, github.com |
Customizing the Image
Build with a specific GSD version:
docker compose -f docker/docker-compose.yml build --build-arg GSD_VERSION=2.43.0
Cleanup
# Docker Sandbox
docker sandbox rm gsd-sandbox
# Docker Compose
docker compose -f docker/docker-compose.yml down -v
Known Limitations
- macOS/Windows only: Docker Sandboxes require Docker Desktop 4.58+. Linux sandbox support is experimental.
- Environment parity: The sandbox runs Ubuntu (Debian). macOS-only dependencies may not work inside the sandbox.
- Named agent registration: Docker Desktop's built-in named agents (claude, codex, etc.) are registered by Docker itself. Third-party tools cannot register new named agents. GSD uses the generic shell sandbox type with a custom template instead.