claude-sandbox

Run Claude Code, Codex or Pi in a container with a bubblewrap sandbox. The sandbox isolates host credentials and IDE sockets, limits writable paths, and blocks access to internal networks except explicitly allowed devices.

Install and run

On a Linux host with uv and rootless Podman:

uv tool install claude-sandbox
cd ~/src/my-project
claude-sandbox

The launcher pulls the matching prebuilt image and starts sandboxed Claude Code in your project. Log in when prompted. Later runs reuse the project's container; agent logins and memory persist across container recreation. No repository clone or devcontainer setup is needed.

Choose another agent with claude-sandbox codex or claude-sandbox pi. The host must provide /dev/net/tun and support unprivileged user namespaces. Rootless Docker is untested; rootless Podman is the supported runtime.

Getting started covers first login and verification. Use the container image covers configuration, persistence and toolchains.

Update

On the host:

uv tool upgrade claude-sandbox
claude-sandbox --recreate

Run the second command in each project you want to update. Recreation removes container-local packages and forge logins; project files and shared agent settings remain. See Upgrade.

Already use a devcontainer?

Inside a Debian/Ubuntu devcontainer, as root:

uvx claude-sandbox install
claude

The container needs --device=/dev/net/tun. For automatic installation on rebuild, follow Sandbox a team devcontainer. Install without uv covers the clone fallback.

What the sandbox protects

Agent tools can be steered by malicious content or make mistakes. The sandbox limits the damage: the project is writable, host secrets are masked, and the network jail blocks lateral access to internal hosts. Run claude-sandbox verify to check the installed isolation.

The project files and credentials you explicitly share remain accessible to the agent, and internet access stays open. Read the threat model for the boundaries and architecture for the implementation.

Documentation and development

Documentation includes guides, configuration reference and design decisions. DLS users start here.

The sandbox implementation is Bash; the PyPI package bundles its launcher and installer. See the contributing guide for tests and the isolated documentation toolchain.

License

See LICENSE.