coding-capsule

Run Claude Code in a sandboxed Docker container. The agent can read/write files in your repo but cannot access anything else on your machine (no SSH keys, AWS credentials, other repos, etc.).

Prerequisites

• Docker installed and running
• Node.js >= 20
• Claude Code authenticated on your host machine (run claude once and log in)

Usage

cd /path/to/repo
npx coding-capsule

This builds a Docker image (if needed), mounts the repo and your Claude credentials into the container, and runs Claude Code in --dangerously-skip-permissions mode.

You can pass additional positional arguments through to Claude:

cd /path/to/repo
npx coding-capsule "fix the failing tests"

Global install

npm install -g coding-capsule
cd /path/to/repo
coding-capsule

CLI options

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --expose-port | -p | — | Forward a host port into the container so that localhost:<port> inside the container reaches the host. Can be specified multiple times. | | --truecolor | — | true | Set COLORTERM=truecolor inside the container. Disable with --no-truecolor. | | --version | — | — | Show version number. | | --help | — | — | Show help. |

# Forward ports 3000 and 8080 into the container
coding-capsule -p 3000 -p 8080

# Disable true-color support
coding-capsule --no-truecolor

What's sandboxed

• Your Claude auth credentials (~/.claude and ~/.claude.json) are snapshotted (copied) into the container — the container cannot modify the originals. Session history and project settings mount directly for persistence.
• No access to ~/.ssh, ~/.aws, ~/.config, or any other host files
• Network is open (the agent needs it for npm, docs, etc.)
• The Docker image is built automatically from an embedded Dockerfile — no manual setup required
• The container runs as the same UID/GID as your host user, so file ownership in the repo is preserved

[!WARNING] Your Claude Code credentials are readable inside the container. A prompt injection attack (e.g., malicious instructions hidden in a repo file) could exfiltrate them over the network. The credentials are only useful for Claude API calls — they cannot access your machine, GitHub, or other services. The exact blast radius depends on the authentication method (OAuth token vs. raw API key). To mitigate this, you could add an egress proxy that restricts outbound traffic to known-good domains.

Security analysis

For a detailed breakdown of the security posture, see blastradius.md — risk profile, attack surface, and mitigations.

Rationale

The problem

Running a coding agent in --dangerously-skip-permissions mode (auto-approve all actions) is convenient but risky. A bad actor can embed prompt injection instructions in repo files (README, code comments, issue descriptions) that trick the agent into running arbitrary commands on your machine — deleting files, exfiltrating secrets, installing backdoors, etc.

We don't care about the agent messing with the repo itself — it's source-controlled and trivially reversible with git checkout . && git clean -fd. The threat is the agent reaching outside the repo to the rest of the local machine.

Approaches considered

Claude Code hooks (command blocklist). Configure hooks that intercept every Bash call and block patterns like rm -rf ~, curl ... | sh, access to ~/.ssh, etc. This is easy to set up but fundamentally a blocklist — a sufficiently creative injection can bypass it via encoding, aliasing, or indirect execution. It's a speed bump, not a wall.

Bubblewrap (bwrap). A lightweight Linux sandboxing tool that uses kernel namespaces (same as Docker) but without a daemon, images, or root access. You selectively mount only the directories the process needs. The advantage over Docker is that auth "just works" since it runs natively on the host. The downside is more fiddly to set up and less familiar to most people.

Docker with --network=none. The strongest isolation — no filesystem access outside the mounted repo, no network. But coding agents legitimately need network access for installing packages, reading library docs, searching npm, etc. So this is too restrictive.

Docker with egress proxy. Run a filtering proxy (e.g., squid) that only allows traffic to known-good domains (npmjs.org, github.com, stackoverflow.com, etc.). This prevents exfiltration while allowing legitimate network use. Effective but high maintenance — you need to keep the allowlist up to date.

Docker with open network and minimal host mounts. Only the repo and Claude credentials are bind-mounted from the host. Network is unrestricted. The agent can't touch anything else on the host machine, but it can make outbound network requests. The only sensitive data it could exfiltrate is the repo's source code and the mounted Claude session credentials.

Dedicated VM. Run the agent on a throwaway cloud instance or local VM with nothing of value on it. Strongest isolation but heaviest setup.

What we chose

Docker with open network and minimal host mounts. It's the pragmatic sweet spot:

• Fully protects the host machine (no access to SSH keys, AWS creds, other repos, etc.)
• Agent can still use the network for legitimate purposes (npm, docs, etc.)
• Simple to set up — npx coding-capsule from your repo directory and you're running
• Repo damage is irrelevant (source-controlled)

The trade-off is that the Claude Code credentials are readable inside the container and could theoretically be exfiltrated over the open network. We accept this because (a) the credentials are only useful for Claude API calls — they cannot access your machine, GitHub, or other services, and (b) adding an egress proxy to close this gap is possible but adds significant complexity.

Undoing changes

The agent can only modify files in the repo you passed in. Since it's source-controlled:

cd /path/to/repo
git checkout .
git clean -fd