What’s installed#

uv tool install claude-sandbox installs the host launcher. The selected image contains the sandbox below; uvx claude-sandbox install installs it into your own devcontainer.

Container files#

Path

Purpose

/usr/local/bin/{claude,codex,pi}

The same three-line wrapper. It runs the sandbox’s own interpreter, which selects an agent profile by command name

/usr/libexec/claude-sandbox/python/

Pinned CPython for the sandbox, pruned to about 60 MB, root-owned and byte-compiled. In the published image it is also the projects’ Python: project venvs link to it but cannot change it

/usr/libexec/claude-sandbox/venv/

The claude_sandbox package and nothing else: it has no runtime dependencies

/usr/libexec/claude-sandbox/uv/

The pinned uv that installed that CPython, kept so a reinstall need not fetch it again. The published image drops it after installation and keeps one uv, its base image’s, for projects

/usr/libexec/claude-sandbox/claude

Claude binary, relocated off PATH

/usr/libexec/claude-sandbox/codex-dist/

Codex release, including its bundled helpers; read-only inside the sandbox

/usr/libexec/claude-sandbox/pi-dist/

Standalone Pi executable and assets; read-only inside the sandbox

/usr/libexec/claude-sandbox/pi-run

Pi launch-marker check; see its limits

/usr/libexec/claude-sandbox/pi-system.md

System-prompt note that tells Pi about the sandbox it runs in

/usr/libexec/claude-sandbox/codex-launch

Codex’s in-jail launch wrapper

/usr/local/bin/claude-sandbox

The claude-sandbox command, run by the same interpreter: gh-auth, glab-auth, update, verify, pi-local, doctor, version

/usr/libexec/claude-sandbox/verify-sandbox-battery.sh

Installed isolation checks

/usr/libexec/claude-sandbox/skills/

Shipped skills, mounted read-only into each agent’s discovery directory

/usr/libexec/claude-sandbox/statusline-command.sh

Recommended Claude status line

/usr/libexec/claude-sandbox/pi-sandbox-tag.ts

Pi footer showing the host and container tag

/usr/libexec/claude-sandbox/version

Installed release or checkout revision

/usr/libexec/claude-sandbox/installer

Records a wheel installation for update instructions

/etc/claude-gitconfig

Curated Git config, refreshed from your identity at agent launch

/etc/claude-code/managed-settings.json

Disables Claude’s updater and makes the claude-sandbox plugin marketplace known (installs no plugin); preserves existing administrator settings and hooks

/etc/codex/managed_config.toml

Disables Codex startup update checks; an administrator-owned file is left unchanged with a warning

/etc/claude-sandbox.conf

Sandbox configuration

The installer adds passt (providing pasta) for the network jail. Custom devcontainers must supply /dev/net/tun through runArgs; the host launcher does this automatically.

Wrappers are installed even if an optional agent download is skipped or fails. They report a missing binary rather than falling through to an unwrapped agent. Use WITH_CODEX=0 or WITH_PI=0 at installation to skip those downloads; PI_VERSION pins Pi’s release. Reinstalling preserves existing agent binaries. See Upgrade.

User state#

Each agent sees only its own state, plus the shared skills and forge stores. With /user-terminal-config mounted, agent state and shared skills persist across rebuilds; forge tokens remain container-local.

Path

Installer behaviour

~/.claude/, ~/.claude.json

Preserve login, settings and hooks; seed a status line only if absent

~/.codex/

Create if absent; preserve configuration, credentials and sessions

~/.pi/agent/

Preserve Pi settings, credentials, extensions and sessions

~/.agents/skills/

Shared writable skills; created if absent, with Claude discovery through symlinks

claude-sandbox doctor --fix replaces the Claude status line with the recommended version, backing up changed files. See container tags and shared skills.

Optional tools#

The published image includes Python, uv, Node.js, npm and Vim. Custom containers keep their own toolchain choices.

The image’s Python is the sandbox’s own pinned interpreter, and uv there never downloads another on its own (UV_PYTHON_DOWNLOADS=manual). For a project that needs a different version, run uv python install 3.12 (for example) from claude-sandbox shell, then recreate the project’s venv; an agent session cannot install one. Don’t run uv python uninstall 3.13 from that shell: it removes the sandbox’s interpreter and every agent launch fails. uvx claude-sandbox --recreate recovers it.

Shipped skills provide installers for optional tools, run outside the agent:

Browser downloads persist under /cache/ms-playwright. After setup, chromium also works from an outer container terminal with a display; its profile lives under /cache/chromium-home.