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.

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

Pluggable inspector chain on every HTTP request, WebSocket frame, and DNS query. 5 built-in inspectors plus custom extensions.

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

Allowlist-based dnsmasq sidecar. Non-allowlisted domains resolve to a placeholder IP, keeping SSRF guards functional.

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.

Isolation Modes

Choose Your Isolation Level

Same inspection logic, different isolation boundaries. Container mode for development, Firecracker for production.

Default

Container Mode

Rootless Podman

  • IsolationLinux namespaces
  • KernelShared with host
  • Escape riskMitigated, not eliminated
  • Root requiredNo
  • macOS supportYes (Podman machine)
  • Boot time~1s
  • Best forDevelopment, CI, low-risk
KVM

Firecracker Mode

Hardware Virtualization

  • IsolationKVM (VT-x / AMD-V)
  • KernelDedicated guest kernel
  • Escape riskEliminated (VM boundary)
  • Root requiredYes
  • macOS supportNo (/dev/kvm required)
  • Boot time~7s
  • Best forProduction, untrusted agents

Built On

mitmproxy Podman Firecracker

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 N/A agentcage doesn't manage agent memory
ASI07 Inter-Agent Comms N/A 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, and web search integration.

--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 4 Steps

1

Install

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

Scaffold a config

agentcage init myapp --scaffold openclaw
3

Store secrets

agentcage secret set myapp ANTHROPIC_API_KEY agentcage secret set myapp OPENCLAW_GATEWAY_PASSWORD
4

Create the cage

agentcage cage create -c cage.yaml

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