claude-docker-sandbox

A security-first CLI wrapper that runs Claude Code inside disposable Docker containers, isolating the AI agent to only your project files with no persistent state.

The Problem

When you run Claude Code normally, it has the same permissions as your user account. That means it can read your SSH keys, AWS credentials, dotfiles, and anything else on your machine. Even with Claude Code's built-in permission system, a prompt injection attack (where malicious content in a file tricks the agent into running unintended commands) could bypass those safeguards.

The safest way to use an AI coding agent is to put it inside a boundary it cannot control.

How This Works

This package wraps Claude Code in a Docker container that:

• Only mounts your project folder. Your home directory, credentials, and system files are completely invisible to the agent.
• Installs Claude Code fresh every session. The agent binary is not baked into the Docker image. It gets installed at runtime and destroyed when you exit.
• Runs as a non-root user. Even inside the container, the agent operates with limited privileges.
• Self-destructs on exit. The --rm flag tells Docker to delete the container the moment you close the session. No leftover credentials, no cached state, nothing.

The container is the security boundary, not the agent's own permission system. That is the key idea behind this project.

Prerequisites

• Docker Desktop or any Docker runtime (Colima, Rancher Desktop, etc.)
• Node.js 18 or later
• A Claude Pro, Max, or Team plan, or an Anthropic API key

Install

npm install -g claude-docker-sandbox

Usage

Navigate to any project directory and run:

cd ~/my-project
claude-sandbox

Or run it without installing:

cd ~/my-project
npx claude-docker-sandbox

On the first run, the CLI will build the Docker image automatically. This takes about a minute. After that, subsequent launches are fast since the image is cached locally.

Claude Code will prompt you to log in. Choose your Claude.ai account (your Pro or Max subscription), not the Console/API option. This avoids extra charges. The login happens inside the container and is destroyed when you exit.

Dev Server Preview

If Claude Code starts a dev server (Astro, Vite, Next.js, etc.), it needs to bind to 0.0.0.0 instead of localhost for you to access it from your browser. For Astro, add this to your astro.config.mjs:

server: {
  host: '0.0.0.0'
}

Then open http://localhost:4321 on your machine as usual.

The default forwarded ports are 4321 and 3000. If your framework uses different ports, you can rebuild the image with custom port mappings by editing the run command in bin/cli.js.

Security Model

| Threat | How it is handled | |--------|-------------------| | Agent reads SSH keys or credentials | Not mounted. Invisible to the container. | | Agent installs malicious packages globally | Container is ephemeral. Destroyed on exit. | | Agent exfiltrates data over the network | Add --network=none to the Docker run command for offline sessions. | | Prompt injection runs destructive commands | Damage is limited to /workspace (your project). No host access. | | Persistent backdoor in agent config | Agent installs fresh every session. No persistent volumes. | | Agent modifies host system files | Only your project directory is mounted. The rest of the host filesystem does not exist inside the container. |

Troubleshooting

docker: command not found on macOS

Docker Desktop sometimes does not add its CLI to your PATH. Fix it by adding this to your ~/.zshrc:

export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"

Then run source ~/.zshrc.

Claude Code asks for a $5 organization fee

This happens when you authenticate through the Console/API path instead of your Pro subscription. Make sure no ANTHROPIC_API_KEY environment variable is set on your system, and choose the Claude.ai account option when logging in.

OAuth login link does not open browser

The container has no browser. Claude Code will print a URL. Copy and paste it into Chrome. Safari may fail with a PKCE S256 error. This is an upstream Claude Code issue.

localhost dev server not accessible from your browser

Your dev server must bind to 0.0.0.0 inside the container, not localhost or 127.0.0.1. Pass a CLI flag like npx astro dev --host 0.0.0.0 or update your framework config.

docker sandbox run fails with darwin/amd64 error

Docker Sandbox microVMs only support Apple Silicon Macs. This package uses standard Docker containers instead, which work on any architecture (Intel Mac, Apple Silicon, Linux, Windows with WSL2).

Project Structure

claude-docker-sandbox/
├── bin/
│   └── cli.js          # CLI entry point
├── docker/
│   └── Dockerfile      # Bundled inside the package
├── package.json
├── README.md
├── LICENSE
└── .gitignore

How It Works Under the Hood

When you run claude-sandbox, the CLI script does three things:

1. Checks if Docker is running. If not, it tells you to start Docker Desktop and exits.
2. Checks if the claude-sandbox image exists locally. If not, it builds it from the Dockerfile bundled inside this package. The Dockerfile creates a minimal Alpine Linux environment with Node.js, git, and bash.
3. Starts an interactive Docker container. Your current directory is mounted at /workspace inside the container. Claude Code is installed into the non-root user's local prefix at runtime, then launched. When you exit, the container and everything inside it is deleted.

The Dockerfile intentionally does not include Claude Code in the image. Installing it at runtime means there is no persistent agent binary and no cached credentials between sessions. The tradeoff is a ~30 second install on each launch, but for a security-focused tool, that is the right call.

Contributing

Issues and pull requests are welcome. If you run into a problem or have an idea for improvement, open an issue on GitHub.

License

MIT