agentcage
Defense-in-depth proxy sandbox for AI agents.
Don't let your agent phone home.
:warning: Warning: This is an experimental project. It has not been audited by security professionals. Use it at your own risk. See Security model for details and known limitations.
Coding agents: Claude Code · Codex · Pi | Agent platforms: OpenClaw
What is it?
agentcage is a CLI that generates hardened, sandboxed environments for AI agents. Your agent runs on an internal-only network with no internet gateway; the only way out is through an inspecting proxy that scans every HTTP request before forwarding it.
Most agent deployments hand the agent a lethal trifecta: internet access, real secrets, and arbitrary code execution. Combined, they create an exfiltration risk that most setups have zero defense against. agentcage breaks that combination. See Security model for the full breakdown.
- Network isolation -- agent on internal-only network, no internet gateway
- Inspecting proxy -- pluggable inspector chain on every HTTP request, WebSocket frame, and DNS query
- Secret injection -- agent gets placeholders, proxy swaps in real values outbound and redacts inbound
- Secret & payload scanning -- regex secret detection, Shannon entropy, content-type mismatch, base64 blob scanning
- DNS filtering -- allowlist-based dnsmasq sidecar, placeholder IPs for unauthorized domains
- Fail-closed by default -- all hardening on out of the box; component failure stops traffic
Three isolation backends are supported:
- container (Linux, default) — rootless Podman containers on the host
- vm (Linux + macOS) — a Lima VM per cage with hardware isolation via KVM
- apple-container (macOS 26+ Apple Silicon, default there) — an Apple
containermicroVM per cage; faster and lighter than Lima.
See Security model for the threat-by-threat matrix and Isolation modes for how each backend works and when to pick which. For the full container topology and inspector chain, see Architecture.
Install
curl -fsSL https://raw.githubusercontent.com/agentcage/agentcage/master/install.sh | sh
The installer detects your platform and installs the right backend (Podman on Linux, Apple container on macOS 26+ Apple Silicon, Lima elsewhere). For manual setup per backend, see Install.
Quick Start
Ephemeral session
One command builds the image, creates a temporary cage, and drops you into an interactive session. The cage is torn down when you exit; audit logs are preserved.
# Run Claude Code in a sandbox (-s prompts for the value if no =VALUE given)
agentcage run claude-code -s ANTHROPIC_API_KEY
# Run OpenAI Codex in a sandbox
agentcage run codex -s OPENAI_API_KEY
# Pass secrets and a project directory
agentcage run claude-code -s ANTHROPIC_API_KEY --project ~/myrepo
# Force a clean rebuild (re-pull the base image, ignore the layer cache)
agentcage run claude-code -s ANTHROPIC_API_KEY --no-cache --pull
Required secrets are enforced up front: run aborts before starting the cage if a scaffold's declared secret (e.g. ANTHROPIC_API_KEY) isn't supplied via -s or resolvable from a configured source:. Every declared secret is mandatory — to run an agent that authenticates without an API key (e.g. claude-code via interactive OAuth login), create a persistent cage with agentcage init and edit its config. --no-cache/--pull force a clean rebuild consistently across the container, vm, and apple-container backends.
Persistent cage
Survives across sessions — keep auth tokens, run multiple cage exec sessions, or let it run continuously as a background service (systemd auto-restarts on failure and starts on boot).
agentcage init myapp --scaffold claude-code
agentcage secret set myapp ANTHROPIC_API_KEY
agentcage cage create -c cage.yaml
agentcage cage exec myapp -- claude # interactive
agentcage cage verify myapp # or just check it's running
Custom image
agentcage init myapp --image node:22-slim
# Edit cage.yaml to configure domains, secrets, inspectors...
agentcage cage create -c cage.yaml
Run agentcage init --list-scaffolds to see available scaffolds. See CLI Reference for the full command set.
Day-to-day
agentcage cage list # what's running
agentcage cage logs myapp # agent logs
agentcage cage audit myapp --summary --since 24h # inspection decisions
agentcage secret set myapp ANTHROPIC_API_KEY # rotate a secret
agentcage cage update myapp -c cage.yaml # apply config changes
agentcage cage destroy myapp # tear it down
See CLI reference for the full command set and Operate a cage for the how-tos.
Documentation
The docs map lays out the tree by task: control egress, operate a cage, extend with a custom inspector, understand the architecture and security model.
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file agentcage-0.39.0.tar.gz.
File metadata
- Download URL: agentcage-0.39.0.tar.gz
- Upload date:
- Size: 1.5 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c382023c849f242f178dcb3ee8afe8b0e210fa0543e7e35bd3ccf139319dcccc
|
|
| MD5 |
8039711a58c2670c73a81461bad20af1
|
|
| BLAKE2b-256 |
a18c0efc0d7d0bc238568c79904ff9433b16fc3cdb72a58601715de1f194ff8b
|
Provenance
The following attestation bundles were made for agentcage-0.39.0.tar.gz:
Publisher:
publish.yml on agentcage/agentcage
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
agentcage-0.39.0.tar.gz -
Subject digest:
c382023c849f242f178dcb3ee8afe8b0e210fa0543e7e35bd3ccf139319dcccc - Sigstore transparency entry: 2713273346
- Sigstore integration time:
-
Permalink:
agentcage/agentcage@ae3ee4f81b5ae4219b4e59138ef17330386c9377 -
Branch / Tag:
refs/tags/v0.39.0 - Owner: https://github.com/agentcage
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@ae3ee4f81b5ae4219b4e59138ef17330386c9377 -
Trigger Event:
push
-
Statement type:
File details
Details for the file agentcage-0.39.0-py3-none-any.whl.
File metadata
- Download URL: agentcage-0.39.0-py3-none-any.whl
- Upload date:
- Size: 518.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
592d551301e744bfc6747d45075cc800c24c915a61472590cf4792c979446ff5
|
|
| MD5 |
daca14b7e0e4395d802153245dc8af99
|
|
| BLAKE2b-256 |
32957141ef15892a05f4f7e025b4416be6e2a6f1626f950250f6f8b7c6352ecc
|
Provenance
The following attestation bundles were made for agentcage-0.39.0-py3-none-any.whl:
Publisher:
publish.yml on agentcage/agentcage
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
agentcage-0.39.0-py3-none-any.whl -
Subject digest:
592d551301e744bfc6747d45075cc800c24c915a61472590cf4792c979446ff5 - Sigstore transparency entry: 2713273681
- Sigstore integration time:
-
Permalink:
agentcage/agentcage@ae3ee4f81b5ae4219b4e59138ef17330386c9377 -
Branch / Tag:
refs/tags/v0.39.0 - Owner: https://github.com/agentcage
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@ae3ee4f81b5ae4219b4e59138ef17330386c9377 -
Trigger Event:
push
-
Statement type:
