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 and run from the same project directory:

claude-sandbox verify

This runs the checks inside the sandbox without starting an agent or needing a login. The same command works in your own devcontainer terminal. 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.

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 runs the helpers, such as verify and gh-auth.

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.