Getting started#

Install the launcher from PyPI, then run it in the project you want Claude Code to work on. The launcher creates the container and sandbox for you.

Already use a project devcontainer? Installing into it is often preferable because the agent gets your project’s existing tooling.

1. Install on your host#

You need Linux, uv, rootless Podman, /dev/net/tun, and unprivileged user namespaces. Check that Podman runs rootless:

podman info --format '{{.Host.Security.Rootless}}'

It should print true. Rootless Docker is untested; use Podman.

In a host terminal, outside any container:

Note

DLS workstations If uv is not on PATH, run module load uv in the host terminal first. For DLS policy and forge access, see Claude Code at DLS.

uv tool install claude-sandbox

If uv reports that its executable directory is missing from PATH, run uv tool update-shell and open a new terminal.

2. Run Claude#

cd ~/src/my-project
claude-sandbox

The first run pulls the image for your installed package version and creates a project container. Claude runs inside its sandbox with the project writable. Log in when prompted, using the code-paste flow if needed.

Ask Claude to inspect the project or make a small change. Review the diff as you normally would: the sandbox limits access, but the agent can still edit or delete files in the project.

3. Check the sandbox#

Exit Claude, then open a container shell:

Already in a devcontainer with the sandbox installed? Skip the first and last lines; run the verification command in your normal container terminal.

claude-sandbox shell        # Skip if already in your devcontainer terminal
claude-sandbox verify
exit                       # Only if you opened the shell above

The shell is outside the inner sandbox; verify launches a sandboxed agent to run the checks. See Verify the sandbox to interpret results.

Keep working#

Run claude-sandbox from the same project to start another session in its existing container. Agent login and memory are shared through ~/.config/terminal-config; forge tokens stay in the project container.

To use another agent: claude-sandbox codex or claude-sandbox pi.
To enable push access: Authenticate with forges.
To update: Upgrade claude-sandbox.
For mounts, configuration and toolchains: Use the container image.

Already use a devcontainer?#

This keeps the agent in your project’s own tooling environment. Install inside your existing Debian/Ubuntu devcontainer as root:

uvx claude-sandbox install
claude

Add "--device=/dev/net/tun" to its runArgs and rebuild before launching an agent. Inside the container, claude, codex and pi launch sandboxed agents; claude-sandbox is the administrative helper.

Throughout these guides, claude-sandbox shell just opens a container terminal. If you are already in your devcontainer terminal, skip that step and the matching exit. The commands between them are identical and run outside an agent session.

For the full setup, including installation on rebuild and login persistence, see Set up a devcontainer and Sandbox a team devcontainer. If uv is unavailable, see Install without uv.