diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9402139..c72ce0d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased]
+- **Sandbox Isolation for Coding Agents** — `guide/sandbox-isolation.md` (NEW), `machine-readable/reference.yaml`, `guide/ultimate-guide.md`
+ - Score: 4/5 (High Value — official Docker docs + verified vendor documentation)
+ - Source: [docs.docker.com/ai/sandboxes/](https://docs.docker.com/ai/sandboxes/) (Docker Desktop 4.58+, Jan 2026)
+ - New guide file: Docker Sandboxes (microVM isolation, network policies, custom templates, supported agents)
+ - Alternatives landscape: Fly.io Sprites, Cloudflare Sandbox SDK, E2B, Vercel Sandboxes, native CC sandbox
+ - Comparison matrix (6 solutions, 7 criteria) + decision tree (Mermaid flowchart)
+ - Safe autonomy workflows: Docker Sandbox + `--dangerously-skip-permissions` pattern, CI/CD sketch
+ - Anti-patterns table (6 entries)
+ - Cross-reference added after `--dangerously-skip-permissions` warning (ultimate-guide.md:3953)
+ - 18 new `sandbox_*` entries in reference.yaml
+ - Evaluation: `docs/resource-evaluations/docker-sandboxes-isolation.md`
+
- **Claude Code releases tracking: v2.1.27** — `machine-readable/claude-code-releases.yaml`, `guide/claude-code-releases.md`
- `--from-pr` flag to resume sessions linked to GitHub PR number/URL
- Sessions auto-linked to PRs when created via `gh pr create`
diff --git a/README.md b/README.md
index b2f9697..3a1a8a2 100644
--- a/README.md
+++ b/README.md
@@ -374,6 +374,7 @@ Claude Code sends your prompts, file contents, and MCP results to Anthropic serv
| **[Workflows](./guide/workflows/)** | Practical guides (TDD, Plan-Driven, Task Management) | 30 min |
| **[Data Privacy](./guide/data-privacy.md)** | Retention & compliance | 10 min |
| **[Security Hardening](./guide/security-hardening.md)** | MCP vetting, injection defense | 25 min |
+| **[Sandbox Isolation](./guide/sandbox-isolation.md)** | Docker Sandboxes, cloud alternatives, safe autonomy | 10 min |
| **[Production Safety](./guide/production-safety.md)** | Port stability, DB safety, infrastructure lock | 20 min |
| **[DevOps & SRE](./guide/devops-sre.md)** | FIRE framework, K8s troubleshooting, incident response | 30 min |
| **[AI Ecosystem](./guide/ai-ecosystem.md)** | Complementary AI tools & integration patterns | 20 min |
@@ -482,7 +483,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
---
-*Version 3.20.1 | January 2026 | Crafted with Claude*
+*Version 3.20.2 | January 2026 | Crafted with Claude*
B{Where?}
+ B -->|Local development| C{Docker Desktop available?}
+ B -->|CI/CD pipeline| D[Cloud sandbox]
+ B -->|Serverless / API| E[Cloudflare Sandbox SDK]
+ B -->|Minimal setup| F[Native CC sandbox mode]
+
+ C -->|Yes| G[Docker Sandboxes
microVM isolation]
+ C -->|No| F
+
+ D --> H{Preference?}
+ H -->|Persistent VMs| I[Fly.io Sprites]
+ H -->|Open-source| J[E2B]
+ H -->|Vercel ecosystem| K[Vercel Sandboxes]
+```
+
+---
+
+## 3. Docker Sandboxes
+
+> **Source**: [docs.docker.com/ai/sandboxes/](https://docs.docker.com/ai/sandboxes/)
+> **Requires**: Docker Desktop 4.58+ (macOS or Windows)
+
+Docker Sandboxes run AI coding agents in microVM-based isolation on your local machine. Each sandbox gets its own private Docker daemon and filesystem. Sandboxes do NOT appear in `docker ps` — they are VMs, not containers.
+
+### Quick Start
+
+```bash
+# Create and run a sandbox with your project
+docker sandbox run claude ~/my-project
+
+# Run with autonomous mode (safe inside sandbox)
+docker sandbox run claude ~/my-project -- --dangerously-skip-permissions
+
+# Pass a prompt directly
+docker sandbox run claude ~/my-project -- "Refactor auth module to use JWT"
+
+# Continue a previous session
+docker sandbox run my-sandbox -- --continue
+```
+
+### Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ HOST MACHINE │
+│ │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ DOCKER SANDBOX (microVM) │ │
+│ │ │ │
+│ │ ┌──────────────┐ ┌───────────────────────────┐ │ │
+│ │ │ Claude Code │ │ Private Docker daemon │ │ │
+│ │ │ (--dsp mode) │ │ (isolated from host) │ │ │
+│ │ └──────────────┘ └───────────────────────────┘ │ │
+│ │ │ │
+│ │ ┌──────────────────────────────────────────────┐ │ │
+│ │ │ Workspace: ~/my-project (synced with host) │ │ │
+│ │ │ Same absolute path as host │ │ │
+│ │ └──────────────────────────────────────────────┘ │ │
+│ │ │ │
+│ │ Base: Ubuntu, Node.js, Python 3, Go, Git, │ │
+│ │ Docker CLI, GitHub CLI, ripgrep, jq │ │
+│ │ User: non-root 'agent' with sudo │ │
+│ └────────────────────────────────────────────────────┘ │
+│ │
+│ Host Docker daemon: NOT accessible from sandbox │
+│ Host filesystem: NOT accessible (except workspace) │
+└──────────────────────────────────────────────────────────┘
+```
+
+Key properties:
+- **Workspace sync**: Host directory mounts at the same absolute path inside the sandbox
+- **Full isolation**: Agent cannot access host Docker daemon, host containers, or files outside workspace
+- **Private Docker**: Each sandbox has its own Docker daemon for building/running containers
+- **Claude runs with `--dangerously-skip-permissions`**: Intentional — the sandbox is the security boundary
+
+### Network Policies
+
+Control what the sandbox can access on the network.
+
+```bash
+# View network activity
+docker sandbox network log my-sandbox
+
+# Set up denylist mode (block all, allow specific)
+docker sandbox network proxy my-sandbox \
+ --policy deny \
+ --allow-host api.anthropic.com \
+ --allow-host "*.npmjs.org" \
+ --allow-host "*.pypi.org" \
+ --allow-host github.com
+
+# Set up allowlist mode (allow all, block specific)
+docker sandbox network proxy my-sandbox \
+ --policy allow \
+ --block-host "*.malicious-domain.com" \
+ --block-cidr "192.168.0.0/16"
+```
+
+| Mode | Default behavior | Use case |
+|------|-----------------|----------|
+| **Allowlist** (default) | Permits most traffic, blocks specific destinations | General development |
+| **Denylist** | Blocks all traffic, allows only specified destinations | High-security environments |
+
+**Default blocked ranges**: Private CIDRs (`10.0.0.0/8`, `127.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`) and IPv6 equivalents.
+
+**Pattern matching**: Exact (`example.com`), port-specific (`example.com:443`), wildcards (`*.example.com` matches subdomains only). Most specific pattern wins.
+
+**Security caveat**: Domain filtering does not inspect traffic content. Broad allowances (e.g., `github.com`) permit access to user-generated content. HTTPS inspection is not performed in bypass mode.
+
+**Config storage**: Per-sandbox at `~/.docker/sandboxes/vm/[name]/proxy-config.json`. Policies persist across restarts.
+
+### Custom Templates
+
+For teams needing reproducible environments with specific tooling:
+
+```dockerfile
+FROM docker/sandbox-templates:claude-code
+
+USER root
+
+# Install project-specific dependencies
+RUN apt-get update && apt-get install -y \
+ postgresql-client \
+ redis-tools
+
+# Install global npm packages
+RUN npm install -g pnpm turbo
+
+USER agent
+```
+
+Build and use:
+
+```bash
+# Build the template
+docker build -t my-team-sandbox:v1 .
+
+# Create sandbox with custom template
+docker sandbox create my-sandbox \
+ --template my-team-sandbox:v1 \
+ --load-local-template ~/my-project
+```
+
+Use custom templates when: team environments, specific tool versions, repeated setups, complex configurations. For simple one-off work, use the defaults and let the agent install what it needs.
+
+### Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `docker sandbox run ` | Create and start a sandbox |
+| `docker sandbox create ` | Create without starting |
+| `docker sandbox ls` | List all sandboxes |
+| `docker sandbox run -- "prompt"` | Pass a prompt |
+| `docker sandbox run -- --continue` | Continue previous session |
+| `docker sandbox run -- --dsp` | Short for --dangerously-skip-permissions |
+| `docker sandbox network proxy ` | Configure network policies |
+| `docker sandbox network log ` | View network activity |
+
+### Authentication
+
+**Option 1: API key (recommended for headless)**
+
+Set `ANTHROPIC_API_KEY` in `~/.bashrc` or `~/.zshrc`. The sandbox daemon reads from these files, not the current shell session. Restart the daemon after changes. Persists across sandbox recreation.
+
+**Option 2: Interactive login (per-session)**
+
+Triggered automatically if no credentials found. Use `/login` inside Claude Code to trigger manually. Authentication does NOT persist when the sandbox is destroyed.
+
+### Supported Agents
+
+| Agent | Provider | Status |
+|-------|----------|--------|
+| Claude Code | Anthropic | Full support |
+| Codex CLI | OpenAI | Supported |
+| Gemini CLI | Google | Supported |
+| cagent | Docker | Supported |
+| Kiro | AWS | Supported |
+
+### Limitations
+
+- **macOS and Windows only** for microVM mode. Linux uses legacy container-based sandboxes (Docker Desktop 4.57+).
+- **Docker Desktop required** — not available with standalone Docker Engine.
+- **MCP Gateway not yet supported** inside sandboxes.
+- **No GPU passthrough** — not suitable for ML training workloads.
+- **Workspace sync is one-way**: changes inside the sandbox propagate to the host, but concurrent host edits may conflict.
+
+---
+
+## 4. Alternatives Landscape
+
+### Fly.io Sprites
+
+> **Source**: [sprites.dev](https://sprites.dev)
+
+Hardware-isolated execution environments built on Firecracker microVMs, by Fly.io.
+
+- **Isolation**: Firecracker microVMs with full hardware isolation
+- **Persistence**: Fully mutable ext4 filesystem, automatic 100GB partition
+- **Checkpoint/restore**: Live checkpoints in ~300ms (copy-on-write), restore under 1 second
+- **HTTP access**: Individual URLs per Sprite, auto-activation on requests (cold-start under 1s)
+- **Network**: Layer 3 egress policies, public/private toggles
+- **Resources**: Up to 8 CPUs, 16GB RAM per Sprite
+- **API**: CLI (`sprite` command), REST API, JavaScript and Go client libraries
+- **Pricing**: Pay-per-use ($0.07/CPU-hour, $0.04/GB-hour). $30 trial credits.
+
+### Cloudflare Sandbox SDK
+
+> **Source**: [developers.cloudflare.com/sandbox/](https://developers.cloudflare.com/sandbox/)
+
+Secure code execution in isolated containers, built on Cloudflare's Workers platform.
+
+- **Isolation**: Containers (not microVMs) on Cloudflare's serverless runtime
+- **Languages**: Python, JavaScript/TypeScript, shell commands
+- **Persistence**: R2 bucket mounting as local filesystem paths
+- **API**: TypeScript SDK (`getSandbox()`, `exec()`, `runCode()`, file ops, WebSocket)
+- **Integration**: Claude generates code, Sandbox executes it, results return as text/visualizations
+- **Pricing**: Workers Paid plan required. Based on Containers platform pricing.
+- **Tutorial**: [developers.cloudflare.com/sandbox/tutorials/claude-code/](https://developers.cloudflare.com/sandbox/tutorials/claude-code/)
+
+### Vercel Sandboxes
+
+> **Source**: [vercel.com/docs/vercel-sandbox/](https://vercel.com/docs/vercel-sandbox/)
+
+Ephemeral Linux microVMs for AI agents and code generation, GA since 2026-01-30.
+
+- **Isolation**: Firecracker microVMs, isolated from env vars, DBs, and cloud resources
+- **Performance**: Sub-second initialization, automatic termination on task completion
+- **Timeouts**: Default 5 min, Hobby up to 45 min, Pro/Enterprise up to 5 hours
+- **SDK**: `Sandbox`, `Command`, `Snapshot` classes. Filesystem snapshots for faster repeated runs.
+- **Auth**: Vercel OIDC tokens (recommended) or access tokens for external CI/CD
+- **Integration**: Works with Claude's Agent SDK for autonomous agent tasks
+
+### E2B
+
+> **Source**: [e2b.dev](https://e2b.dev)
+
+Open-source sandbox platform for AI agents and LLM applications.
+
+- **Isolation**: Firecracker microVMs (same technology as AWS Lambda)
+- **Performance**: ~150ms cold boot, under 25ms standby resume
+- **Custom images**: Up to 10GB, boot in under 2 seconds (Blueprints)
+- **Snapshots**: Capture and restore full VM state
+- **Languages**: Python, JavaScript, Ruby, C++, anything on Linux. LLM-agnostic.
+- **Integrations**: LangChain, LangGraph, LlamaIndex, Vercel/Next.js, Ollama
+- **Deployment**: Cloud-hosted, BYOC (AWS/GCP/Azure), self-hosted on-premises/VPC
+- **Pricing**: Free tier ($100 credits, 1h max), Pro from $150/month (24h max)
+
+### Native Claude Code Sandbox Mode
+
+> **Source**: [code.claude.com/docs/en/sandboxing](https://code.claude.com/docs/en/sandboxing)
+
+Claude Code's built-in process-level sandboxing (Layer 4 in the [architecture](./architecture.md)).
+
+- **No external dependencies**: Works out of the box
+- **Process isolation**: Restricts what commands Claude can execute
+- **Configurable**: Through `allowedTools` in settings
+- **Limitations**: Not full VM isolation — shares host kernel and filesystem
+
+Use this when: Docker is unavailable, lightweight isolation is sufficient, or you want defense-in-depth alongside a sandbox.
+
+---
+
+## 5. Comparison Matrix
+
+| Criterion | Docker Sandboxes | Fly.io Sprites | Cloudflare SDK | E2B | Vercel Sandboxes | Native CC |
+|-----------|-----------------|----------------|----------------|-----|-----------------|-----------|
+| **Isolation level** | microVM | Firecracker microVM | Container | Firecracker microVM | Firecracker microVM | Process |
+| **Runs locally** | Yes | No (cloud) | No (cloud) | No (cloud) | No (cloud) | Yes |
+| **Docker-in-Docker** | Yes (private daemon) | Yes | No | Yes | Yes | N/A |
+| **Network control** | Allow/Deny lists | L3 egress policies | Not detailed | Not detailed | Not detailed | N/A |
+| **Platform** | macOS, Windows | Any (API) | Any (Workers) | Any (API/SDK) | Any (SDK) | Any |
+| **Free tier** | Docker Desktop | $30 credits | Workers Paid | $100 credits | Yes (limited) | Free |
+| **Best for** | Local dev | API-driven agents | Serverless | Multi-framework | Next.js/Vercel | Minimal setup |
+
+---
+
+## 6. Safe Autonomy Workflows
+
+### Pattern: Docker Sandbox + --dangerously-skip-permissions
+
+The recommended pattern for local autonomous development:
+
+```bash
+# 1. Create a sandbox with your project
+docker sandbox create my-feature ~/my-project
+
+# 2. Configure network (optional, recommended for security)
+docker sandbox network proxy my-feature \
+ --policy deny \
+ --allow-host api.anthropic.com \
+ --allow-host "*.npmjs.org" \
+ --allow-host github.com
+
+# 3. Run Claude autonomously (safe inside sandbox)
+docker sandbox run my-feature -- --dangerously-skip-permissions \
+ "Refactor the auth module to use JWT. Run all tests before finishing."
+
+# 4. Review changes on host (workspace syncs automatically)
+cd ~/my-project && git diff
+
+# 5. If satisfied, commit. If not, discard or re-run.
+git add -A && git commit -m "feat: JWT auth (sandbox-generated)"
+```
+
+### Pattern: CI/CD Pipeline with Sandbox
+
+Sketch for GitHub Actions:
+
+```yaml
+jobs:
+ agent-task:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Run Claude in E2B sandbox
+ uses: e2b-dev/e2b-github-action@v1
+ with:
+ api-key: ${{ secrets.E2B_API_KEY }}
+ command: |
+ claude --dangerously-skip-permissions \
+ -p "Run the full test suite and fix any failures"
+```
+
+For CI/CD, cloud sandboxes (E2B, Vercel, Sprites) are typically better than Docker Sandboxes since they don't require Docker Desktop.
+
+---
+
+## 7. Anti-Patterns
+
+| Anti-pattern | Why it's dangerous | Do instead |
+|-------------|-------------------|------------|
+| `--dangerously-skip-permissions` without sandbox | Agent has unrestricted access to host filesystem, network, and Docker | Use a sandbox as the security boundary |
+| Assuming containers = VMs | Containers share the host kernel. A container escape exposes the host. | Use microVM-based solutions (Docker Sandboxes, E2B, Sprites) for strong isolation |
+| Mounting entire filesystem into sandbox | Defeats the purpose of isolation. Agent can access credentials, SSH keys, etc. | Mount only the project workspace directory |
+| Allowlisting `*` in network policies | Agent can exfiltrate data to any endpoint | Use denylist mode with explicit allowances |
+| Skipping `git diff` review after sandbox run | Autonomous agent may have made unintended changes | Always review diffs before committing sandbox-generated code |
+| Using sandbox as excuse to skip code review | Isolation protects the host, not code quality | Sandbox + code review are complementary, not alternatives |
+
+---
+
+## See Also
+
+- [architecture.md](./architecture.md) — Layer 4 (Sub-Agent Architecture) and permission model
+- [security-hardening.md](./security-hardening.md) — MCP vetting, injection defense, CVE tracking
+- [code.claude.com/docs/en/sandboxing](https://code.claude.com/docs/en/sandboxing) — Official Claude Code sandbox docs
+- [docs.docker.com/ai/sandboxes/](https://docs.docker.com/ai/sandboxes/) — Docker Sandboxes documentation
diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md
index 5358ae2..408841c 100644
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@@ -10,7 +10,7 @@
**Last updated**: January 2026
-**Version**: 3.20.1
+**Version**: 3.20.2
---
@@ -3950,6 +3950,8 @@ Horror stories from r/ClaudeAI include:
**Always prefer granular `allowedTools` over disabling permissions entirely.**
+> **Safe alternative**: For autonomous execution, run Claude Code inside [Docker Sandboxes](sandbox-isolation.md) or a similar isolated environment. The sandbox becomes the security boundary, making `--dangerously-skip-permissions` safe to use. See the [Sandbox Isolation Guide](sandbox-isolation.md) for setup instructions and alternatives.
+
### Dynamic Memory (Profile Switching)
**Concept**: Temporarily modify CLAUDE.md for specific tasks, then restore.
@@ -15766,4 +15768,4 @@ We'll evaluate and add it to this section if it meets quality criteria.
**Contributions**: Issues and PRs welcome.
-**Last updated**: January 2026 | **Version**: 3.20.1
+**Last updated**: January 2026 | **Version**: 3.20.2
diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml
index 661f098..b47c883 100644
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@@ -3,8 +3,8 @@
# Source: guide/ultimate-guide.md
# Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
-version: "3.20.1"
-updated: "2026-01-30"
+version: "3.20.2"
+updated: "2026-01-31"
# ════════════════════════════════════════════════════════════════
# DEEP DIVE - Line numbers in guide/ultimate-guide.md
@@ -99,6 +99,26 @@ deep_dive:
tts_ai_ecosystem: "guide/ai-ecosystem.md:507"
tts_hook_example: "examples/hooks/bash/tts-selective.sh"
tts_claude_md_template: "examples/claude-md/tts-enabled.md"
+ # Sandbox Isolation for Coding Agents (guide/sandbox-isolation.md) - Added 2026-01-31
+ sandbox_isolation_guide: "guide/sandbox-isolation.md"
+ sandbox_isolation_decision_tree: "guide/sandbox-isolation.md:40"
+ sandbox_docker_sandboxes: "guide/sandbox-isolation.md:61"
+ sandbox_docker_network: "guide/sandbox-isolation.md:121"
+ sandbox_docker_templates: "guide/sandbox-isolation.md:165"
+ sandbox_docker_docs: "https://docs.docker.com/ai/sandboxes/"
+ sandbox_docker_claude_config: "https://docs.docker.com/ai/sandboxes/claude-code/"
+ sandbox_docker_network_docs: "https://docs.docker.com/ai/sandboxes/network-policies/"
+ sandbox_docker_templates_docs: "https://docs.docker.com/ai/sandboxes/templates/"
+ sandbox_flyio_sprites: "https://sprites.dev"
+ sandbox_cloudflare_sdk: "https://developers.cloudflare.com/sandbox/tutorials/claude-code/"
+ sandbox_vercel: "https://vercel.com/docs/vercel-sandbox/"
+ sandbox_e2b: "https://e2b.dev"
+ sandbox_native_cc: "guide/architecture.md:390"
+ sandbox_evaluation: "docs/resource-evaluations/docker-sandboxes-isolation.md"
+ sandbox_safe_autonomy: "guide/sandbox-isolation.md:320"
+ sandbox_anti_patterns: "guide/sandbox-isolation.md:372"
+ sandbox_comparison_matrix: "guide/sandbox-isolation.md:306"
+ sandbox_score: "4/5"
# Architecture internals (guide/architecture.md)
architecture_visual_overview: "guide/architecture.md:41"
architecture_visual_source: "https://www.linkedin.com/posts/mohamed-ali-ben-salem-2b777b9a_en-ce-moment-je-vois-passer-des-posts-du-activity-7420592149110362112-eY5a"
@@ -271,7 +291,7 @@ deep_dive:
gsd_note: "Overlap with existing patterns (Ralph Loop, Gas Town, BMAD)"
# Resource Evaluations (added 2026-01-26)
resource_evaluations_directory: "docs/resource-evaluations/"
- resource_evaluations_count: 22
+ resource_evaluations_count: 23
resource_evaluations_methodology: "docs/resource-evaluations/README.md"
resource_evaluations_appendix: "guide/ultimate-guide.md:15034"
resource_evaluations_readme_section: "README.md:278"
@@ -832,7 +852,7 @@ ecosystem:
- "Cross-links modified → Update all 4 repos"
history:
- date: "2026-01-20"
- event: "Code Landing sync v3.20.1, 66 templates, cross-links"
+ event: "Code Landing sync v3.20.2, 66 templates, cross-links"
commit: "5b5ce62"
- date: "2026-01-20"
event: "Cowork Landing fix (paths, README, UI badges)"