agentcage 0.28.0

Defense-in-depth proxy sandbox for AI agents

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 container microVM 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