release: v3.20.2 - Sandbox Isolation for Coding Agents

New guide file covering Docker Sandboxes (microVM isolation),
cloud alternatives (Fly.io Sprites, E2B, Vercel, Cloudflare),
safe autonomy workflows, and comparison matrix.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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`

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*
 
 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,

VERSION

@@ -1 +1 @@
-3.20.1
+3.20.2

docs/resource-evaluations/README.md

@@ -55,7 +55,8 @@ Les documents de travail bruts (prompts Perplexity, audits clients) restent dans
 | **System Prompts** (Official vs Community) | 4/5 | **2/5** | ⚠️ Watch only (official sources exist) | [system-prompts-official-vs-community.md](./system-prompts-official-vs-community.md) |
 | **Worktrunk** | 4/5 | **4/5** | ✅ Intégré (workflow) | [worktrunk-evaluation.md](./worktrunk-evaluation.md) |
 | **Pat Cullen** (Multi-Agent PR Review) | 5/5 | **5/5** | ✅ Intégré (review-pr, code-reviewer, guide) | [017-pat-cullen-final-review.md](./017-pat-cullen-final-review.md) |
+| **Docker Sandboxes** (Isolation Landscape) | 4/5 | **4/5** | ✅ Intégré (guide + notice) | [docker-sandboxes-isolation.md](./docker-sandboxes-isolation.md) |
 
 ---
 
-**Dernier update**: 2026-01-30 (17 évaluations)
+**Dernier update**: 2026-01-31 (18 évaluations)

docs/resource-evaluations/docker-sandboxes-isolation.md

@@ -0,0 +1,64 @@
+# Resource Evaluation: Docker Sandboxes & Sandbox Isolation Landscape
+
+| Field | Value |
+|-------|-------|
+| **Resource** | Docker Sandboxes blog + [docs.docker.com/ai/sandboxes/](https://docs.docker.com/ai/sandboxes/) |
+| **Type** | Product launch + official documentation |
+| **Published** | 2026-01-30 |
+| **Score** | **4/5** (High Value) |
+| **Action** | Integrated — new guide file + reference.yaml + cross-references |
+
+---
+
+## Summary
+
+1. **Docker Sandboxes** (Docker Desktop 4.58+) provide microVM-based isolation for AI coding agents, replacing the older container-based approach. Claude Code runs with `--dangerously-skip-permissions` inside the sandbox since the VM itself is the security boundary.
+2. **Network policies** offer allowlist/denylist modes with domain-level filtering, per-sandbox config, and built-in monitoring via `docker sandbox network log`. Private CIDR ranges blocked by default.
+3. **Custom templates** use standard Dockerfiles extending `docker/sandbox-templates:claude-code`. Base image includes Ubuntu, Node.js, Python 3, Go, Git, Docker CLI, GitHub CLI, ripgrep, jq.
+4. **The broader landscape** includes Fly.io Sprites (Firecracker microVMs, ~300ms checkpoint/restore), Cloudflare Sandbox SDK (container-based, Workers integration), E2B (open-source Firecracker, 150ms cold boot), and Vercel Sandboxes (GA 2026-01-30, Firecracker microVMs).
+5. **Gap in the guide**: No existing documentation on running Claude Code in isolated environments. The `--dangerously-skip-permissions` warning (ultimate-guide.md:3943) lacks a safe alternative path.
+
+## Gap Analysis
+
+| Topic | Before | After |
+|-------|--------|-------|
+| Safe autonomous execution | Warning only ("never use --dsp") | Documented pattern: sandbox + --dsp |
+| Docker Sandboxes | Not mentioned | Full guide with commands, network, templates |
+| Cloud sandbox alternatives | Not mentioned | 4 alternatives with comparison matrix |
+| Isolation decision tree | Missing | Flowchart: local vs cloud vs serverless |
+| Network policy configuration | Missing | Allowlist/denylist modes documented |
+| Custom template creation | Missing | Dockerfile pattern documented |
+
+## Integration Decision
+
+**Score justification**: 4/5 (High Value) rather than 5/5 because:
+- Docker Sandboxes are genuinely useful and fill a real gap (safe autonomy)
+- Official Docker documentation is reliable (Tier 1 source)
+- However, the feature is Docker Desktop-only (no standalone Docker Engine support)
+- Linux support limited to legacy container mode (not microVM)
+- MCP Gateway not yet supported inside sandboxes
+- Cloud alternatives are supplementary context, not Claude Code-specific features
+
+**Action**: Create dedicated guide file (`guide/sandbox-isolation.md`) covering Docker Sandboxes as the primary solution with alternatives for cloud/CI scenarios.
+
+## Fact-Check
+
+| Claim | Verification | Status |
+|-------|-------------|--------|
+| Docker Sandboxes use microVMs, not containers | docs.docker.com/ai/sandboxes/ | Verified |
+| Claude Code runs with --dsp inside sandbox | docs.docker.com/ai/sandboxes/claude-code/ | Verified |
+| Supported agents: Claude Code, Codex, Gemini, cagent, Kiro | docs.docker.com/ai/sandboxes/ | Verified |
+| Network allowlist/denylist modes | docs.docker.com/ai/sandboxes/network-policies/ | Verified |
+| macOS + Windows only for microVM mode | docs.docker.com/ai/sandboxes/ | Verified |
+| Fly.io Sprites use Firecracker microVMs | sprites.dev | Verified |
+| E2B cold boot ~150ms | e2b.dev | Claimed by vendor |
+| Vercel Sandboxes GA 2026-01-30 | vercel.com announcement | Verified |
+| Cloudflare uses containers, not microVMs | developers.cloudflare.com/sandbox/ | Verified |
+
+## Integration Applied
+
+- `guide/sandbox-isolation.md` — New guide file (~10 min read)
+- `machine-readable/reference.yaml` — 13 new sandbox_* index entries
+- `guide/ultimate-guide.md:3943` — Cross-reference added after --dsp warning
+- `guide/README.md` — Navigation entry added
+- `docs/resource-evaluations/README.md` — Index entry added

guide/README.md

@@ -20,6 +20,7 @@ Core documentation for mastering Claude Code.
 | [security-hardening.md](./security-hardening.md) | Security threats, MCP vetting, injection defense | 25 min |
 | [ai-traceability.md](./ai-traceability.md) | AI attribution, disclosure policies, git-ai, compliance | 20 min |
 | [devops-sre.md](./devops-sre.md) | FIRE framework for infrastructure diagnosis and incident response | 30 min |
+| [sandbox-isolation.md](./sandbox-isolation.md) | Docker Sandboxes, cloud alternatives, safe autonomy workflows | 10 min |
 | [ai-ecosystem.md](./ai-ecosystem.md) | Complementary AI tools (Perplexity, Gemini, Kimi, NotebookLM, TTS) | 30 min |
 | [cowork.md](./cowork.md) | Claude Cowork: Summary (see [dedicated repo](https://github.com/FlorianBruniaux/claude-cowork-guide) for full docs) | 5 min |
 | [workflows/](./workflows/) | Practical workflow guides for Claude Code | 30 min |

guide/cheatsheet.md

@@ -6,7 +6,7 @@
 
 **Written with**: Claude (Anthropic)
 
-**Version**: 3.20.1 | **Last Updated**: January 2026
+**Version**: 3.20.2 | **Last Updated**: January 2026
 
 ---
 
@@ -484,4 +484,4 @@ where.exe claude; claude doctor; claude mcp list
 
 **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
 
-*Last updated: January 2026 | Version 3.20.1*
+*Last updated: January 2026 | Version 3.20.2*

guide/sandbox-isolation.md

@@ -0,0 +1,390 @@
+# Sandbox Isolation for Coding Agents
+
+> **Confidence**: Tier 2 — Official Docker docs + verified vendor documentation
+> **Reading time**: ~10 minutes
+> **Scope**: Running Claude Code safely in isolated environments
+
+---
+
+## TL;DR
+
+| Solution | Isolation | Local/Cloud | Best For |
+|----------|-----------|-------------|----------|
+| **Docker Sandboxes** | microVM | Local | Daily autonomous dev work |
+| **Fly.io Sprites** | Firecracker microVM | Cloud | API-driven agent workflows |
+| **E2B** | Firecracker microVM | Cloud | Multi-framework AI apps |
+| **Vercel Sandboxes** | Firecracker microVM | Cloud | Next.js / Vercel ecosystem |
+| **Cloudflare Sandbox SDK** | Container | Cloud | Workers-based serverless |
+| **Native CC sandbox** | Process-level | Local | Lightweight, no Docker needed |
+
+Quick start:
+
+```bash
+docker sandbox run claude ~/my-project
+```
+
+---
+
+## 1. The Problem: Safe Autonomy
+
+Claude Code's permission system protects you from unintended actions. But it creates a tension:
+
+- **`--dangerously-skip-permissions`** removes all guardrails — Claude can `rm -rf`, `git push --force`, or `DROP TABLE` without asking. On a bare host, this is dangerous.
+- **Permission fatigue** — approving every file edit and shell command slows down autonomous workflows. For large refactors or CI pipelines, interactive approval is impractical.
+- **The gap**: How do you run Claude Code autonomously AND safely?
+
+**Answer**: Isolate the execution environment. Let the agent run free inside a sandbox where the blast radius is contained. The sandbox is the security boundary, not the permission system.
+
+---
+
+## 2. Isolation Approaches
+
+```mermaid
+flowchart TD
+    A[Need autonomous Claude Code] --> 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<br/>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 <agent> <path>` | Create and start a sandbox |
+| `docker sandbox create <name>` | Create without starting |
+| `docker sandbox ls` | List all sandboxes |
+| `docker sandbox run <name> -- "prompt"` | Pass a prompt |
+| `docker sandbox run <name> -- --continue` | Continue previous session |
+| `docker sandbox run <name> -- --dsp` | Short for --dangerously-skip-permissions |
+| `docker sandbox network proxy <name>` | Configure network policies |
+| `docker sandbox network log <name>` | 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

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

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"
+version: "3.20.2"
-updated: "2026-01-30"
+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)"