agentcage

Don't let your agent phone home.

Defense-in-depth security sandbox for autonomous AI agents. Your agent runs on an internal-only network with no internet gateway — the only way out is through a Rust egress proxy that inspects every HTTP request, swaps decoy secrets for the real ones on the wire, and logs every decision.

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

GitHub Documentation MIT License

Rust egress proxy Linux · macOS Single static binary

The Problem

The Lethal Trifecta

Most agent deployments hand the agent three things that, combined, create an exfiltration risk most setups have zero defense against.

Real Secrets

API keys, tokens, and credentials injected directly into the agent's environment.

Internet Access

Unrestricted outbound connectivity to any server on the internet.

Code Execution

Arbitrary code execution with full access to the local filesystem.

agentcage breaks this combination. The agent never holds real secrets, the only path to the internet is an inspected proxy, and container hardening limits execution scope.

Defense-In-Depth

Eight Independent Defense Layers

Every request must cross eight protective rings. A failure in any one layer does not compromise the others, and every failure narrows egress rather than widening it.

1. Network Confinement

Workload attaches to an unrouted Internal=true bridge. iptables FORWARD DROP, IPv6 disabled, and non-HTTP protocols dropped unless explicitly allowed.

2. DNS Filtering & Sinkholing

dnsmasq answers only allowlisted names. Everything else resolves to 198.51.100.1 (RFC 5737 TEST-NET-2), so denied requests fail fast with a clear policy error. IP literals and wildcard-DNS SSRF tricks are rejected.

3. Proxy Identity Checks

Strict TLS SNI ↔ HTTP Host equality defeats domain fronting. Runtime-granted hosts are refused if they resolve to private, loopback or link-local addresses, and passthrough names are pinned to their real destination.

4. L7 Content Inspectors

A chain run on worker threads: domain allowlist, 20 credential patterns, body-size limits, opt-in Shannon entropy, and content-type mismatch detection — plus your own WebAssembly inspectors with a CPU and memory budget.

5. Zero-Leak Secrets

The agent only ever sees agentcage:secret:KEY:<hex> decoys. The proxy swaps in real values on the wire and redacts them inbound — including percent-encoded, JSON-escaped and base64 forms.

6. Process Confinement

Workload runs as UID 1000 with all capabilities dropped, no-new-privileges, and rootless user namespaces mapping container root to an unprivileged host subuid.

7. Filesystem Isolation

Read-only rootfs, with tmpfs pivot masks over .git/hooks/ and .claude/ so a rogue agent cannot plant hooks that run on your host. Host ~/.ssh and ~/.aws are out of reach.

8. Autonomous Auditing

Structured audit.jsonl and HAR 1.2 capture of every transaction, plus an in-egress Decider Agent and a background Traffic Watcher that can revoke grants on its own.

How It Works

Two Components, One Choke Point

A workload sandbox and an egress gateway share a private, internal-only network. The gateway owns the network boundary and is the agent's only route out.

Agent Makes a Request

The workload has no gateway to the internet. Its default route reaches only the egress gateway, so every connection is forced through inspection.

DNS Decides

dnsmasq resolves allowlisted zones upstream. Anything not permitted returns the TEST-NET-2 sinkhole address, where the proxy answers with an explicit denial.

Egress Inspects

The Rust egress terminates TLS with a per-cage CA, checks SNI/Host identity and rebinding, and runs the inspector chain over the request and any WebSocket messages.

Inject, Forward, or Block

Decoy placeholders are swapped for real secrets on the wire, clean requests are forwarded over verified TLS, and suspicious ones get a JSON 403. Everything is audit-logged and HAR-exportable.

Autonomous Defense

Policy and Watchdog Agents

agentcage doesn't only enforce the rules you wrote — it can negotiate and re-examine them while the agent runs.

Policy API & Decider Agent

The agent can inspect reachable domains at https://agentcage.local/v1/allowlist and request new access with a justification. An in-egress LLM decider adjudicates requests and grants temporary runtime access under a rate limit — and fails closed, denying on any error or timeout.

Traffic Watcher

An opt-in background LLM agent re-reads recent audit logs and capture windows looking for subtle exfiltration, beaconing, or injection. It is narrowing-only: it can revoke a compromised runtime grant in real time, but can never add one.

Isolation Backends

Choose Your Isolation Level

Same inspection logic, different isolation boundaries. agentcage auto-selects the best backend for your host, and you can override it per cage.

Default

Container

Rootless Podman — Linux

IsolationUser namespaces + cgroups v2
KernelShared with host
Escape riskMitigated, not eliminated
Startup< 1s
Secrets at restsystemd-creds (TPM2)
Best forDev, CI, trusted hosts

macOS

Apple Container

Native microVMs — macOS 26+ Apple Silicon

IsolationTwo lightweight VZ microVMs
KernelDedicated guest kernel
Escape riskHardware boundary
Startup~1–2s
Secrets at restmacOS Keychain
Best formacOS Apple Silicon

Lima VM

QEMU / Apple VZ — macOS & Linux

IsolationDedicated Linux VM
KernelDedicated guest kernel
Escape riskHardware boundary
Startup~10–15s
Secrets at restKeychain / systemd-creds
Best forIntel Macs, untrusted agents

Security Coverage

OWASP Top 10 for Agentic Applications

How agentcage maps to the OWASP agentic risk categories. See the full security model for the threat model, trust boundaries, and residual risks.

OWASP Risk	Coverage	How
ASI01 Agent Goal Hijack	Out of scope	agentcage inspects network traffic, not agent intent
ASI02 Tool Misuse	Strong	Domain allowlist, WebSocket inspection, DNS filtering and sinkholing limit reachable services
ASI03 Identity / Privilege Abuse	Strong	Decoy placeholders keep real credentials out of the agent; runtime grants are scoped and expiring
ASI04 Supply Chain	Partial	Checksum-verified agent installs and sandboxed WebAssembly inspectors; dependencies are not universally pinned
ASI05 Unexpected Code Execution	Strong	Read-only rootfs, dropped capabilities, no-new-privileges, rootless user namespaces
ASI06 Memory & Context Poisoning	Out of scope	agentcage doesn't manage agent memory
ASI07 Insecure Inter-Agent Comms	Out of scope	Single-agent scope; all egress is still inspected
ASI08 Cascading Failures	Strong	Fail-closed on proxy errors and bad configs, per-host rate limiting, systemd auto-restart
ASI09 Human-Agent Trust Exploitation	Strong	Every allow, block and error is recorded in structured audit logs with HAR capture
ASI10 Rogue Agents	Strong	Network isolation, multi-layer inspection, DNS filtering, and the autonomous Traffic Watcher

Quick Start

Up and Running in Minutes

Install

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

Run an ephemeral session

One command builds the sandbox, mounts the current project, prompts for the key securely, and tears everything down on exit.

agentcage run claude-code -s ANTHROPIC_API_KEY

Or scaffold a persistent cage

agentcage init my-cage --scaffold claude-code

Store the key encrypted

agentcage secret set my-cage ANTHROPIC_API_KEY

Build and start the cage

agentcage cage create -c cage.yaml

Interact, audit & export

agentcage cage shell my-cage && agentcage cage audit my-cage --summary

Full network forensics: agentcage cage har my-cage -o audit.har