agentcage

agentcage

Defense-in-depth security sandbox for autonomous AI agents.

Default-deny network egress • Zero-leak placeholder secret injection • TLS inspection proxy • Autonomous Policy API & Traffic Watcher • Multi-backend isolation (Linux rootless Podman, macOS Apple Container, Lima VM)

---

agentcage runs an AI coding agent — Claude Code, OpenAI Codex, Pi, OpenClaw, or any custom agent workload — inside an isolated sandbox whose only route to the outside world is an inspecting proxy you control.

The agent gets a working internet connection restricted to approved domains, cryptographically random decoy tokens instead of your real API keys, and zero ability to access the open internet, probe internal networks, or pivot back to your host machine.

agentcage run claude-code -s ANTHROPIC_API_KEY

That single command builds an unprivileged container, allocates a private internal network, launches an egress proxy with a DNS filter and TLS-inspecting inspector chain, stores your real API key encrypted on the host, hands the agent a fake placeholder token, mounts your current repository at /workspace with host-pivot protection masks, and drops you into an interactive Claude Code session.

---

Why agentcage?

Autonomous AI coding agents read untrusted input from the web, execute shell commands, install dependencies, and manipulate files. Running an agent directly on your machine or inside a naive container hands it what security researchers term the lethal trifecta: access to private credentials, arbitrary code execution, and unrestricted network egress.

Standard containerization alone does not protect you:

1. Unrestricted Egress: A standard container can dial any IP on the internet. A prompt-injected agent or malicious dependency can trivially exfiltrate your entire repository or open a reverse shell to an attacker's C2 server.
2. Exposed Credentials: Environment variables like ANTHROPIC_API_KEY or GITHUB_TOKEN are readable by every process in the container, any installed npm/pip package, and any prompt injection that executes env or curl.
3. Internal Network Probing: Containers can reach RFC 1918 private subnets, your local LAN services, and cloud metadata endpoints (169.254.169.254), exposing internal databases and cloud IAM credentials.
4. Host Pivoting via Workspace Mounts: A rogue agent can silently drop a malicious hook into /workspace/.git/hooks/ or a malicious configuration into /workspace/.claude/ that executes arbitrary code on your host upon your next manual commit.

agentcage eliminates each of these attack surfaces:

---

System Architecture

Every cage consists of a workload sandbox and an egress gateway container operating on an isolated, internal-only bridge network (Internal=true), orchestrated by systemd user quadlets (Linux) or microVM supervisors (macOS):

┌─────────────────────────── HOST MACHINE ───────────────────────────────────────────┐
│                                                                                    │
│  agentcage CLI (create, run, exec, domain, secret, watcher, doctor)                │
│  State & Encrypted Secrets: ~/.config/agentcage/ (systemd-creds / Apple Keychain)  │
│                                                                                    │
│  ┌───────────── Private Network: <name>-net (10.89.X.0/24, Internal=true) ─────┐   │
│  │                                                                             │   │
│  │   ┌──────────────────────────┐          ┌────────────────────────────────┐  │   │
│  │   │  WORKLOAD SANDBOX (cage) │          │  EGRESS GATEWAY (egress)       │  │   │
│  │   │  10.89.X.2               │          │  10.89.X.10                    │  │   │
│  │   │                          │          │                                │  │   │
│  │   │  Coding Agent Process    │          │  dnsmasq (DNS Filter)          │  │   │
│  │   │  • UID 1000 (workload)   │  DNS/53  │  • Allowlisted zones → upstream│  │   │
│  │   │  • All capabilities drop │─────────▶│  • Blocked zones → 198.51.100.1│  │   │
│  │   │  • No-new-privileges     │          │    (TEST-NET-2 sinkhole)       │  │   │
│  │   │  • Read-only rootfs      │  TCP     │                                │  │   │
│  │   │  • Pivot masks on .git   │─────────▶│  mitmdump (Inspecting Proxy)   │  │   │
│  │   │                          │          │  • :8080 HTTP proxy            │  │   │
│  │   │  Decoy Placeholders:     │          │  • :8443 transparent (iptables)│  │   │
│  │   │  agentcage:secret:KEY:…  │          │                                │  │   │
│  │   │                          │          │  Proxy Addon & Controls:       │  │   │
│  │   │  Trusted Per-Cage CA:    │          │  • Inspector Chain             │  │   │
│  │   │  /certs/ca-cert.pem      │          │    (domain, secrets, entropy,  │  │   │
│  │   └──────────────────────────┘          │     content-type, body-size)   │  │   │
│  │                │                        │  • Wire Secret Injector        │  │   │
│  │                │ Default route via      │  • Inbound Response Redactor   │  │   │
│  │                └──────▶ 10.89.X.10      │  • Policy API (agentcage.local)│  │   │
│  │                                         │  • Traffic Watcher Agent       │  │   │
│  │                                         │  • Protocol Relays (IMAP/SMTP) │  │   │
│  │                                         └───────────────┬────────────────┘  │   │
│  └─────────────────────────────────────────────────────────│───────────────────┘   │
│                                                            │ iptables:             │
│                                                            │  FORWARD policy DROP  │
│                                                            │  IPv6 FORWARD DROP    │
└────────────────────────────────────────────────────────────│───────────────────────┘
                                                             ▼
                                                     INTERNET / APIs
                                                (allowlisted domains only)

Outbound Request Lifecycle

When an agent performs an HTTPS call (e.g. GET https://api.anthropic.com/v1/messages):

1. DNS Resolution: The agent queries dnsmasq. If anthropic.com is in the allowlist, it forwards upstream and returns the real A/AAAA record. If not, it resolves to 198.51.100.1 (RFC 5737 TEST-NET-2 sinkhole) so unauthorized destinations fail immediately with clear policy errors instead of silent timeouts.
2. Transparent Interception: TCP port 443 is redirected by kernel iptables PREROUTING into the local mitmdump proxy on port 8443.
3. Identity & Anti-Rebinding Checks: The proxy enforces strict SNI ↔ Host equality and verifies that the resolved peer IP is a globally routable public address (blocking DNS rebinding to internal subnets).
4. Inspector Chain: Offloaded to worker threads to keep latency minimal:
   • domain: Verifies destination against permanent allowlists and active runtime grants.
   • secrets: Scans payloads with regex patterns; detects raw credentials leaving the sandbox.
   • entropy: Computes Shannon entropy (0–8 bits/byte) to catch encrypted or obfuscated exfiltration payloads.
   • content-type: Flags base64 blobs disguised inside JSON or plain text.
   • body-size: Enforces strict request body limits.
5. Wire Secret Injection: Decoy placeholders (agentcage:secret:ANTHROPIC_API_KEY:<hex>) are substituted with the real secret on the wire — only for matching allowlisted domains and credential-bearing headers (Authorization, x-api-key, etc.).
6. Upstream Request: Sent to upstream servers over verified TLS.
7. Inbound Redaction: The proxy scans the server response; any echoed real secret is redacted back to its placeholder before reaching the cage.
8. Forensic Logging: Decisions are written to audit.jsonl and full HTTP transactions are recorded in capture.jsonl (exportable as HAR 1.2).

---

Key Features

• Strict Default-Deny Egress: Private container network (Internal=true). L4 iptables drop all forwarding by default; IPv6 is disabled outright. Non-HTTP protocols (TCP/UDP/ICMP) are dropped unless explicitly permitted in cage.yaml.
• Zero-Leak Secret Injection: The sandboxed agent never touches your real API keys. Decoy entropic tokens are swapped on the wire outbound and redacted inbound. An agent tricked into printing its environment only leaks harmless placeholders.
• Encrypted At-Rest Storage: Real secrets are encrypted at rest using systemd-creds on Linux and the macOS Keychain on Darwin.
• Autonomous Policy API: Sandboxed agents can query https://agentcage.local/v1/allowlist to discover reachable domains and POST /v1/allowlist/requests to request dynamic domain access with a justification. An in-egress LLM Decider Agent scrutinizes the justification and grants temporary runtime access without operator intervention.
• Autonomous Traffic Watcher: An opt-in background LLM agent re-examines audit logs and capture windows to detect subtle exfiltration, beaconing, or injection patterns, and can autonomously revoke compromised runtime grants in real time.
• Host Pivot Protection: Project mounts hide .git/hooks/ and .claude/ via tmpfs masks (notmpcopyup and tmpcopyup), preventing agents from planting malicious git hooks that execute on your host machine.
• Dual-Perspective HAR Forensics: Export complete network traffic via agentcage cage har loadable into Chrome DevTools — choosing either the inbound view (safe to share, placeholders only) or outbound view (wire-level debugging with real injected values).
• First-Class Scaffolds: Pre-packaged, hardened templates for popular coding agents (Claude Code, Pi, OpenAI Codex, OpenClaw, and minimal base distros).

---

Backend Support Matrix

agentcage automatically selects the optimal isolation backend for your host machine:

---

30-Second Quickstart

1. Install agentcage

Using the official one-line installer:

curl -fsSL https://raw.githubusercontent.com/agentcage/agentcage/master/install.sh | sh

Or install via Python package managers (uv or pip):

uv tool install agentcage
# or
pip install agentcage

Verify your host environment:

agentcage doctor

2. Ephemeral Session (One-Command Run)

Run an interactive coding agent in a temporary, sandboxed cage with your repository mounted. The cage is automatically torn down when the session exits:

# Run Claude Code in the current project directory (prompts for key securely)
agentcage run claude-code -s ANTHROPIC_API_KEY

# Run OpenAI Codex with an explicit project directory
agentcage run codex --project ~/code/my-repo -s OPENAI_API_KEY

# Run Pi terminal harness with a specific isolation backend
agentcage run pi --project . --isolation vm -s OPENAI_API_KEY

3. Persistent Cage

For continuous background agents, services, or multi-session workflows:

# 1. Generate a commented cage.yaml configuration
agentcage init my-cage --scaffold claude-code

# 2. Store your API key encrypted on the host
agentcage secret set my-cage ANTHROPIC_API_KEY

# 3. Build, generate quadlets, and start the cage
agentcage cage create -c cage.yaml

# 4. Attach an interactive shell or exec commands
agentcage cage exec my-cage -- claude
agentcage cage shell my-cage

# 5. Monitor and audit live traffic
agentcage cage logs my-cage -f
agentcage cage audit my-cage --follow --decision blocked

---

CLI Cheat Sheet & Aliases

agentcage provides top-level aliases for all common operations (agentcage run, agentcage exec, agentcage ls, etc.):

CAGE LIFECYCLE
  agentcage init [NAME] [--scaffold NAME]     Scaffold a new cage.yaml
  agentcage run <scaffold> -s KEY [--project] Launch ephemeral agent session (auto-cleanup)
  agentcage cage create -c cage.yaml          Build, install, and start persistent cage
  agentcage cage update NAME [--no-cache]     Rebuild images and restart cage
  agentcage start | stop | restart NAME       Control cage lifecycle (skips rebuild)
  agentcage destroy NAME [-y] [--keep-secrets]Stop containers, remove quadlets and state
  agentcage prune [-y]                        Remove exited interactive/ephemeral cages
  agentcage verify NAME                       Run runtime health diagnostics

WORKLOAD INTERACTION
  agentcage exec NAME -- CMD                  Execute a command inside the cage container
  agentcage exec NAME -s egress -- CMD        Execute a command inside the egress proxy
  agentcage shell NAME [--as-root]            Open an interactive shell in the cage
  agentcage logs NAME -f [-s egress]          Stream systemd journalctl container logs

EGRESS DOMAINS & GRANTS
  agentcage domain list NAME                  List allowlisted, blocked, and passthrough domains
  agentcage domain add NAME DOMAIN...         Add domains to filter (--expires-in 2h)
  agentcage domain rm NAME DOMAIN             Remove a domain from the filter list
  agentcage cage grants NAME list             List active runtime Policy API grants
  agentcage cage grants NAME promote DOMAIN   Promote dynamic grant into static cage.yaml
  agentcage cage grants NAME revoke DOMAIN    Immediately drop dynamic runtime grant
  agentcage cage grants NAME sync             Reconcile expired or accepted grants

SECRET MANAGEMENT
  agentcage secret set NAME KEY [--declare]   Store secret encrypted on host
  agentcage secret list NAME                  List stored secrets and injection bindings
  agentcage secret rm NAME KEY                Remove a stored secret
  agentcage secret rotate-placeholders NAME   Mint fresh random 128-bit decoy placeholders

FORENSICS & WATCHER
  agentcage cage audit NAME --summary         View aggregated proxy inspection statistics
  agentcage cage audit NAME -f -d blocked     Stream blocked traffic decisions in real time
  agentcage cage har NAME -o audit.har        Export HTTP flows as HAR 1.2 (inbound/outbound)
  agentcage watcher status NAME               Inspect background traffic watcher state
  agentcage watcher findings NAME             Review suspicious flow findings and revocations

CONFIG & MAINTENANCE
  agentcage edit NAME                         Open cage.yaml in $EDITOR with live validation
  agentcage doctor                            Check host dependencies and backend health
  agentcage scaffold list | show | create     Manage built-in and custom scaffolds
  agentcage cage backup NAME -o backup.tar.gz Backup cage configuration and state
  agentcage cage restore BACKUP.tar.gz        Restore or clone cage from backup archive

---

Built-In Scaffolds

Scaffolds package container definitions, volume mounts, and network policies tailored to specific agent harnesses:

Custom scaffolds can be created, edited, and shared across your team using agentcage scaffold create my-scaffold --from claude-code.

---

Configuration Quick Reference (cage.yaml)

agentcage configurations use standard YAML (cage.yaml):

name: my-agent
isolation: container         # container | apple-container | vm (default: auto)
lifecycle: service           # service | interactive | ephemeral

container:
  image: node:22-slim
  command: ["bash"]
  user: 1000:1000
  read_only: true
  drop_capabilities: [ALL]
  no_new_privileges: true
  volumes:
    - ".:/workspace:rw"
  tmpfs:
    - "/tmp:rw,noexec,nosuid,size=512m"

domains:
  mode: allowlist
  allow:
    - api.anthropic.com
    - github.com
    - registry.npmjs.org
  passthrough: []            # Raw TCP TLS passthrough (bypasses MITM inspection)

secrets:
  backend: auto              # systemd-creds (Linux) or keychain (macOS)

secret_injection:
  - env: ANTHROPIC_API_KEY
    inject_to:
      - api.anthropic.com
    inject_headers: true
    inject_body: false

agents:
  decider:
    enable: true             # In-egress autonomous LLM decider for Policy API
  watcher:
    enable: true             # Background LLM auditor for traffic anomaly detection
    interval_seconds: 300
    auto_revoke: true

capture:
  enable_har: true
  max_body_size: 1048576     # 1 MB body capture limit

Full configuration reference: docs/reference/configuration.md.

---

Documentation Index

Explore the complete technical documentation in docs/:

• Get Started: Detailed installation guides, distribution packages, prerequisites, and a step-by-step Quickstart Tutorial.
• Architecture & Concepts: Deep dive into network namespaces, Isolation Backends, the 8-layer Security Model, the Policy API, and the Traffic Watcher.
• Reference Manuals: Complete specifications for cage.yaml, the CLI Manual, the Policy API HTTP Spec, Scaffolds, and Secrets Management.
• How-To Guides: Practical operational recipes for Running Agent Harnesses, Managing Egress & Domains, Troubleshooting & Diagnostics, Backup & Restore, and Custom Inspectors.

---

Security & Disclosure

agentcage is an active defense-in-depth security harness. While it drastically reduces the threat surface of autonomous code execution, security is a continuous discipline. Always review project mounts, domain allowlists, and passthrough grants.

If you discover a security vulnerability in agentcage, please report it privately according to our Security Policy.

License

Licensed under the MIT License.