claude-box runs Claude Code inside a rootless Podman container, isolated to the project directory from which it is launched.
It supports:
- Native Claude models
- SAIA models through an internal LiteLLM proxy
- A configurable Bifrost/OpenAI-compatible gateway through an internal LiteLLM proxy
Claude Code is an agent. It can read files, execute commands, install packages, modify code, and access the network. Running it directly on a workstation can expose more than the project you intended to share.
Potential risks include:
- A process running as your user can normally read many unrelated files.
- Files, dependencies, web content, and command output can contain prompt injections.
- Environment variables may contain API keys, cloud credentials, and tokens.
- SSH agents, GPG agents, and authenticated sockets can allow impersonation.
- An agent with network access could leak data it can read.
- Claude Code’s own permissions and sandbox features are not a complete security boundary.
claude-box reduces this exposure by putting Claude Code behind a rootless container boundary. By default, it shares only the current project and a dedicated per-project home, passes only selected environment variables, and blocks access to the host and private/local networks.
This makes permission-free agent operation more practical: Claude can work freely inside the project without receiving the same access as a normal process running directly on your workstation.
claude-box reduces risk; it does not make untrusted code harmless.
Claude can read and modify the mounted project, access its persistent project-specific state, and communicate with permitted internet services. It could therefore leak information stored in those locations.
Keep secrets out of project directories. Carefully review extra mounts, environment variables, proxy settings, published ports, disabled firewall rules, and ALLOW_PTRACE=1.
- Claude Code in an Ubuntu 24.04 container
- Python 3.12,
uv, Poetry, Git, and common command-line tools - Access to the current project, but not the rest of the host filesystem
- Separate sessions, settings, and caches for each project and backend
- Internet access while blocking the host and private/local networks
- Optional SAIA and Bifrost support through LiteLLM
- Isolation of gateway keys from the Claude Code process
- An optional shell inside the same sandbox
Claude can create virtual environments and run commands such as:
pip install -e .
uv sync
poetry install
pytestChanges to the project and its project-specific home persist. Other container changes disappear when the container exits.
On Ubuntu or Debian:
sudo apt update
sudo apt install -y podman uidmap iproute2On Fedora:
sudo dnf install -y podmanVerify the installation:
podman infoRun claude-box as your normal user, not with sudo.
Install Podman and the ip compatibility command:
brew install podman iproute2macCreate and start the Podman virtual machine:
podman machine init --cpus 4 --memory 8192 --disk-size 50
podman machine startIf a machine already exists:
podman machine startVerify the installation:
podman info
ip -o addr show scope globalInternal gateways may require VPN routes and internal DNS to be available inside the Podman virtual machine.
From the directory containing Containerfile:
podman build -t claude-box:latest -f Containerfile .The first build may take several minutes because the image includes Python, Poetry, uv, and LiteLLM.
Confirm that the image exists:
podman image exists localhost/claude-box:latest
echo $?A result of 0 means the image was found.
Assuming the launcher is named claude-box:
sudo install -m 0755 claude-box /usr/local/bin/claude-boxAlternatively, install it for only your user:
mkdir -p ~/.local/bin
install -m 0755 claude-box ~/.local/bin/claude-boxMake sure ~/.local/bin is in your PATH:
export PATH="$HOME/.local/bin:\$PATH"Inspect the resolved setup:
claude-box --box-infoCreate a long-lived Claude setup token:
claude setup-tokenIf Claude Code is not installed on the host, run it from the image:
podman run --rm -it localhost/claude-box:latest setup-tokenCreate the configuration directory:
mkdir -p ~/.config/claude-box
chmod 700 ~/.config/claude-boxSave the token without putting it in shell history:
umask 077
cat > ~/.config/claude-box/tokenPaste the token, press Enter, then press Ctrl-D:
chmod 600 ~/.config/claude-box/tokenYou may instead provide CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY through the environment.
SAIA mode uses an internal LiteLLM proxy:
Claude Code
│ Anthropic Messages API and dummy token
▼
LiteLLM on container loopback
│ OpenAI-compatible API and real key
▼
SAIA
mkdir -p ~/.config/claude-box
chmod 700 ~/.config/claude-box
umask 077
cat > ~/.config/claude-box/saia-keyPaste the key, press Enter, then press Ctrl-D:
chmod 600 ~/.config/claude-box/saia-keyAn exported SAIA_API_KEY takes precedence over this file.
claude-box --saia-modelsclaude-box --saia MODEL_IDTo configure a default model, add it to:
~/.config/claude-box/config
For example:
SAIA_MODEL='deepseek-v4-flash-0731'Then run:
claude-box --saiaclaude-box uses the following order to determine the context window:
- An explicit
SAIA_CONTEXT_TOKENSvalue - Metadata returned by SAIA’s
/modelsendpoint - A conservative fallback of 32,768 tokens
Some SAIA models do not return context metadata. In that case, you will see:
the gateway does not report a context window for MODEL; using the conservative 32768-token fallback
This is informational. The model can still run.
Using a value lower than the model’s real limit is safe, but Claude will compact conversations earlier. A value higher than the gateway’s actual limit can cause long requests to fail.
If you know the model’s effective context size, add it to ~/.config/claude-box/config:
SAIA_MODEL='deepseek-v4-flash-0731'
SAIA_CONTEXT_TOKENS=65536Replace 65536 with the value documented by the gateway administrator.
To change the general fallback instead:
SAIA_DEFAULT_CONTEXT_TOKENS=65536The built-in fallback is:
SAIA_DEFAULT_CONTEXT_TOKENS=32768An explicit SAIA_CONTEXT_TOKENS overrides both gateway metadata and the fallback.
Bifrost mode connects Claude Code to a configurable OpenAI-compatible gateway through LiteLLM:
Claude Code
│ Anthropic Messages API and dummy token
▼
LiteLLM on container loopback
│ OpenAI-compatible API and real key
▼
Configured Bifrost gateway
No Bifrost hostname, endpoint, model, CA file, or quota endpoint is built into claude-box.
Create or edit:
~/.config/claude-box/config
For example:
mkdir -p ~/.config/claude-box
chmod 700 ~/.config/claude-box
nano ~/.config/claude-box/configAt minimum, add the gateway URL:
BIFROST_URL='https://gateway.example.org/v1'Optionally add a default model:
BIFROST_MODEL='model-id'Protect the configuration:
chmod 600 ~/.config/claude-box/configThe configuration is sourced as a shell fragment. Do not put untrusted shell code in it.
umask 077
cat > ~/.config/claude-box/bifrost-keyPaste the key, press Enter, then press Ctrl-D:
chmod 600 ~/.config/claude-box/bifrost-keyAn exported BIFROST_KEY takes precedence over this file.
claude-box --bifrost-modelsBy default, the model endpoint is:
<BIFROST_URL>/models
If the deployment uses another endpoint, add it to ~/.config/claude-box/config:
BIFROST_MODELS_URL='https://gateway.example.org/custom/models'The model list may include embedding, image, or other non-chat models. Claude Code requires a conversational model with chat completion and tool-calling support.
Specify a model:
claude-box --bifrost MODEL_IDOr configure a default:
BIFROST_MODEL='MODEL_ID'Then run:
claude-box --bifrostIf the gateway’s TLS certificate is signed by an internal organizational CA, add the path to its PEM CA certificate or CA bundle to the claude-box configuration file:
~/.config/claude-box/config
For example:
BIFROST_URL='https://gateway.example.org/v1'
BIFROST_MODEL='model-id'
BIFROST_CA_FILE='/path/to/organization-ca-bundle.pem'BIFROST_CA_FILE must point to a readable certificate file on the host.
claude-box mounts the file read-only into the container and uses it for model-list requests and for the LiteLLM proxy’s TLS verification.
Check that the file is readable:
test -r /path/to/organization-ca-bundle.pem \
&& echo "CA file is readable"If the gateway certificate is already trusted by the container’s standard CA bundle, omit BIFROST_CA_FILE.
TLS verification remains enabled. claude-box does not use curl -k.
claude-box uses the following order:
- An explicit
BIFROST_CONTEXT_TOKENSvalue - Metadata returned by the model-list endpoint
- A conservative fallback of 32,768 tokens
If the gateway does not return context metadata, the 32,768-token fallback is used automatically.
To configure the selected model’s known limit, add this to ~/.config/claude-box/config:
BIFROST_CONTEXT_TOKENS=65536Replace 65536 with the gateway’s effective limit.
To change the general fallback:
BIFROST_DEFAULT_CONTEXT_TOKENS=65536The built-in fallback is:
BIFROST_DEFAULT_CONTEXT_TOKENS=32768The maximum requested output defaults to 8,192 tokens. To change it:
BIFROST_MAX_OUTPUT_TOKENS=16000Quota APIs are deployment-specific, so there is no default quota URL.
If the gateway provides one, add it to ~/.config/claude-box/config:
BIFROST_QUOTA_URL='https://gateway.example.org/api/quota'
BIFROST_QUOTA_HEADER='x-bf-vk'Query it with:
claude-box --bifrost-quotaExample ~/.config/claude-box/config:
# Required Bifrost endpoint
BIFROST_URL='https://gateway.example.org/v1'
# Default model
BIFROST_MODEL='model-id'
# Optional internal CA file on the host
BIFROST_CA_FILE='/path/to/organization-ca-bundle.pem'
# Optional explicit context limit for the selected model
# BIFROST_CONTEXT_TOKENS=65536
# Fallback when the gateway reports no context metadata
BIFROST_DEFAULT_CONTEXT_TOKENS=32768
# Maximum requested output
BIFROST_MAX_OUTPUT_TOKENS=8192
# Optional endpoint overrides
# BIFROST_MODELS_URL='https://gateway.example.org/v1/models'
# BIFROST_QUOTA_URL='https://gateway.example.org/api/quota'
# BIFROST_QUOTA_HEADER='x-bf-vk'The real SAIA or Bifrost key is held by a separate LiteLLM process running under a dedicated UID. Claude Code receives only a dummy token.
When the firewall is enabled, the proxy UID can contact the configured gateway but not arbitrary destinations.
Do not enable ALLOW_PTRACE=1 in gateway mode unless required. It may allow the agent to inspect the proxy process and recover the key.
Start native Claude from a project:
cd ~/projects/my-project
claude-boxPass arguments to Claude Code:
claude-box -c
claude-box -p "Explain this project"Use SAIA:
claude-box --saia MODEL_ID
claude-box --saia MODEL_ID -cUse Bifrost:
claude-box --bifrost MODEL_ID
claude-box --bifrost MODEL_ID -cUseful commands:
claude-box --box-info
claude-box --box-shell
claude-box --saia-models
claude-box --bifrost-models
claude-box --bifrost-quotaWrapper options must appear before Claude Code options.
Native Claude, SAIA, and Bifrost sessions use separate project homes, so -c does not resume a session created with another backend.
By default, the container can access only:
- The current project directory, read-write
- A project-specific home mounted at
/claude, read-write /etc/localtime, read-only- Explicit shared items and extra mounts
- A configured Bifrost CA file, read-only
The rest of the host filesystem is not mounted.
When the firewall is enabled, or a gateway is used, the container starts as root inside rootless Podman’s user namespace.
This limited container-root identity:
- Installs the nftables firewall.
- Starts the isolated LiteLLM proxy when needed.
- Switches to your normal UID and GID.
- Removes capabilities.
- Starts Claude Code or the shell.
This is not host root.
Claude can install dependencies into user-writable locations:
python3 -m venv .venv
. .venv/bin/activate
pip install -e .It can also use:
uv sync
poetry installClaude cannot normally use apt install after privileges have been dropped.
The container is removed when Claude exits.
These locations persist:
- The current project
- Claude sessions and settings
- Project-specific caches
- Virtual environments in the project or
/claude
System-level container changes do not persist.
By default, the container can reach the public internet but cannot connect to:
- The host
- Private IPv4 ranges
- Carrier-grade NAT ranges
- Link-local networks
- Private IPv6 networks
- Multicast ranges
In SAIA or Bifrost mode, the proxy UID is limited to the configured gateway and explicit exceptions.
The main configuration file is:
~/.config/claude-box/config
Common settings:
# General
FIREWALL=1
READ_ONLY=0
MEMORY_LIMIT='8g'
TMP_SIZE='2g'
PERMISSION_MODE='bypassPermissions'
# Image
CLAUDE_BOX_IMAGE='localhost/claude-box:latest'
# SAIA
SAIA_MODEL='model-id'
# Optional explicit model context:
# SAIA_CONTEXT_TOKENS=65536
# Fallback when metadata is unavailable:
SAIA_DEFAULT_CONTEXT_TOKENS=32768
SAIA_MAX_OUTPUT_TOKENS=8192
# Bifrost
BIFROST_URL='https://gateway.example.org/v1'
BIFROST_MODEL='model-id'
BIFROST_CA_FILE='/path/to/organization-ca-bundle.pem'
# Optional explicit model context:
# BIFROST_CONTEXT_TOKENS=65536
# Fallback when metadata is unavailable:
BIFROST_DEFAULT_CONTEXT_TOKENS=32768
BIFROST_MAX_OUTPUT_TOKENS=8192Only configure options you need.
podman build -t claude-box:latest -f Containerfile .podman machine start
podman infoCheck the token:
ls -l ~/.config/claude-box/token
chmod 600 ~/.config/claude-box/tokenAn old exported SAIA_API_KEY may override the key file:
env -u SAIA_API_KEY claude-box --saia-modelsIf that works:
unset SAIA_API_KEYOtherwise, update ~/.config/claude-box/saia-key.
Add it to ~/.config/claude-box/config:
BIFROST_URL='https://gateway.example.org/v1'There is intentionally no built-in Bifrost URL.
Add the host CA file path to ~/.config/claude-box/config:
BIFROST_CA_FILE='/path/to/organization-ca-bundle.pem'Do not disable TLS verification.
This is supported. claude-box automatically uses 32,768 tokens.
To use a known value, add one of these to ~/.config/claude-box/config:
SAIA_CONTEXT_TOKENS=65536or:
BIFROST_CONTEXT_TOKENS=65536Replace the value with the selected model’s documented effective limit.
Claude Code may warn that a third-party model is not in its internal catalog. This does not necessarily prevent the model from working.
claude-box supplies an explicit context limit from gateway metadata or the 32,768-token fallback. The catalog warning may still appear, but Claude Code should use the supplied limit.
The Podman virtual machine may not inherit internal VPN routes or DNS. Test connectivity inside it:
podman machine sshCheck the organization’s VPN and Podman networking configuration.
claude-box --box-infoThis displays the image, project mount, backend, authentication source, context policy, network, and firewall status without printing secret values.