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>
105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
docker compose -f docker/docker-compose.yml build --build-arg GSD_VERSION=2.43.0
|
|
```
|
|
|
|
## Cleanup
|
|
|
|
```bash
|
|
# 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.
|