agentcage

Don't let your agent phone home.

Defense-in-depth proxy sandbox 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.

curl -fsSL https://raw.githubusercontent.com/agentcage/agentcage/master/install.sh | sh
GitHub Documentation MIT License
Experimental project — not yet audited by security professionals. Use at your own risk.

See It In Action

90-Second Demo

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 gets real secrets, the only path to the internet is through an inspecting proxy, and container hardening limits execution scope.

Defense-In-Depth

Multiple Defense Layers

Every HTTP request passes through multiple independent inspection layers. A failure in any one layer doesn't compromise the others.

Network Isolation

Agent on a Podman --internal network with no internet gateway. The only path out is through the inspecting proxy.

Inspecting Proxy

Transparent iptables interception of all outbound HTTP/HTTPS — no per-app proxy config needed. Pluggable inspector chain on every request, WebSocket frame, and DNS query.

Secret Injection

Agent gets placeholders, proxy swaps in real values outbound and redacts inbound. The agent never holds real secrets.

Secret & Payload Scanning

19 regex patterns for common secret formats, Shannon entropy analysis, content-type mismatch detection, and base64 blob scanning.

DNS Filtering

dnsmasq sidecar with allowlist and blocklist modes. TLS passthrough for protocols that break under MITM. Non-permitted domains resolve to a placeholder IP.

Fail-Closed by Default

If the proxy goes down, the agent gets connection errors — not unfiltered internet. All hardening is on out of the box.

How It Works

Three-Container Topology

Agent, DNS sidecar, and inspecting proxy on an internal network with no internet gateway.

1

Agent Makes Request

The agent sends an HTTP request. It has no internet gateway — traffic can only reach the proxy container.

2

DNS Resolution

The dnsmasq sidecar resolves domains against the allowlist. Non-allowlisted domains get a placeholder IP.

3

Proxy Inspection

mitmproxy runs the inspector chain: domain filtering, secret injection, regex scanning, entropy analysis, and custom inspectors.

4

Forward or Block

Clean requests are forwarded to the internet. Suspicious requests get a 403 with a JSON explanation. All decisions are audit-logged with optional HAR capture for forensic analysis.

Isolation Modes

Choose Your Isolation Level

Same inspection logic, different isolation boundaries. Container mode for fast iteration, VM mode for production.

Default

Container Mode

Rootless Podman — Linux only

  • IsolationLinux namespaces
  • KernelShared with host
  • Escape riskMitigated, not eliminated
  • Root requiredNo
  • PlatformsLinux, WSL2
  • Boot time~1s
  • Best forDevelopment, CI, low-risk
VM

VM Mode

Lima — Linux & macOS

  • IsolationKVM (Linux) / Apple VZ (macOS)
  • KernelDedicated guest kernel
  • Escape riskEliminated (VM boundary)
  • Root requiredNo
  • PlatformsLinux, macOS (Apple Silicon)
  • Boot time~10s
  • Best forProduction, untrusted agents, macOS

Security Coverage

OWASP Top 10 for Agentic Applications

How agentcage maps to the 2026 OWASP agentic risk categories. See the full threat model for details.

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 limit reachable services
ASI03 Identity / Privilege Abuse Strong Secret injection prevents agent from holding real credentials
ASI04 Supply Chain Strong Pinned image digests, pinned deps, inspector path validation
ASI05 Code Execution Strong Read-only rootfs, dropped capabilities, no-new-privileges
ASI06 Memory Poisoning Out of scope agentcage doesn't manage agent memory
ASI07 Inter-Agent Comms Out of scope Single-agent scope
ASI08 Cascading Failures Strong Fail-closed on proxy down, systemd auto-restart, per-host rate limiting
ASI09 Human Trust Strong Persistent structured audit logging with all decisions logged by default
ASI10 Rogue Agents Strong Network isolation, multi-layer inspection, DNS filtering, WebSocket inspection

Setup Guides

Works With Your Agent

Pre-built scaffolds with sensible defaults for popular AI agents. Run agentcage init --list-scaffolds to see all available options.

OpenClaw

Full-featured AI coding agent with browser UI, device pairing, nested containers, and headless Chrome.

--scaffold openclaw

PicoClaw

Ultra-lightweight AI agent gateway. ~10 MB image, ~10-20 MB RAM. Minimal footprint.

--scaffold picoclaw

NanoClaw

Agent framework that spawns nested containers. Podman-in-podman with Docker CLI shim.

--scaffold nanoclaw

Quick Start

OpenClaw in 5 Steps

1

Install

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

Scaffold a config

agentcage init myagent --scaffold openclaw
3

Create the cage with secrets

agentcage cage create -c cage.yaml -s ANTHROPIC_API_KEY=sk-ant-...
4

Verify it's running

agentcage cage list && agentcage cage verify myagent
5

Inspect & interact

cage show myagent && cage shell myagent

Contributing

Fork the repo, create a feature branch, add tests, and submit a PR. Keep changes focused — one concern per PR.

Contribution Guide

Report a Vulnerability

Do not open a public issue for security vulnerabilities. Email security@agentcage.ai instead. You will receive an acknowledgment within 48 hours.

Security Policy

Built On

mitmproxy Podman Lima