Agentcage
Checked: 2026-07-14
Summary
Agentcage is an experimental, MIT-licensed command-line tool that builds local sandboxes for AI agents. It places the agent on an internal-only network and forces outbound HTTP, HTTPS, WebSocket, and DNS traffic through a separate inspecting gateway. The gateway applies domain policy, scans payloads, injects real credentials only after inspection, and records decisions.
It supports a lightweight rootless-container boundary or a stronger dedicated VM or Apple microVM boundary.
Problem
An agent with arbitrary code execution, internet access, and real credentials can leak source code or secrets through a normal-looking request. Basic containers limit file access but do not inspect authorized traffic or keep credentials away from the agent process. Agentcage tries to break this combination with layered isolation and an inspected network path.
How It Works
- A cage runs the untrusted agent with no internet gateway.
- A separate egress sibling holds the proxy, DNS filter, firewall policy, credentials, and audit log. It is the only route to the internet.
- DNS returns real addresses for allowed zones and a placeholder address for other names. The egress gateway makes the final policy decision.
- A TLS-intercepting proxy decrypts HTTP traffic, runs an ordered inspector chain, injects credentials, forwards approved requests, and redacts secrets from responses.
- Default inspected ports are 80 and 443. Unlisted ports are dropped unless explicitly configured for inspected or uninspected forwarding.
- Ephemeral
agentcage runsessions are deleted on exit while audit logs remain. Persistent cages keep agent state and may run as a background service. - Structured audit logs record blocked and flagged decisions; logging allowed traffic is optional.
Security Boundary
Agentcage offers three backends:
| Backend | Boundary | Platform |
|---|---|---|
container | Rootless Podman namespaces; shared host kernel | Linux |
vm | One Lima VM with a dedicated guest kernel per cage | Linux, Intel and Apple Silicon macOS |
apple-container | Two Apple microVMs on a per-cage network | macOS 26+ on Apple Silicon |
- Container mode uses a read-only root filesystem, drops Linux capabilities, applies
no-new-privileges, and runs the egress as non-root. - VM modes protect the host from a workload container or guest-kernel escape better than shared-kernel container mode.
- Network failure is designed to fail closed: if the egress sibling stops, the cage loses connectivity rather than gaining unfiltered access.
- Base images are pinned by digest, paths and names are validated, and templates render in a sandboxed environment.
- The maintainers explicitly say Agentcage is experimental, unaudited, and not guaranteed secure.
Platforms and Agents
- Scaffolds: Claude Code, OpenAI Codex, Pi, and OpenClaw.
- Linux defaults to rootless Podman container isolation.
- macOS 26+ Apple Silicon defaults to Apple
container; other supported Macs use Lima. - The installer selects a backend automatically. Configuration can choose another supported backend.
- Custom images and custom inspectors are supported.
- Unknown: native Windows support is not documented.
Setup
- Run the official installer, which selects Podman, Apple
container, or Lima for the host. - For a temporary session, run an agent scaffold with
agentcage run, provide required credentials, and optionally mount a project. - For persistence, use
agentcage init, store credentials, create the cage, and enter it withcage exec. - Configure allowed domains, secret routing, inspectors, rate limits, ports, and audit behavior in
cage.yaml. - Use cage list, logs, audit, verify, update, backup, and destroy commands for ongoing operation.
Network and Credentials
- The workload has no direct internet gateway. HTTP, HTTPS, WebSocket, and DNS traffic go through the egress sibling.
- Domain policy can allow or block destinations. DNS types outside the supported policy are refused.
- Built-in inspectors check domains, known secret patterns, body size, optional high entropy, content-type mismatches, and encoded blobs.
- Real credentials stay in the egress sibling. The agent receives generated placeholders; the proxy swaps in real values only for approved destinations after inspection.
- Responses are redacted so returned credential values become placeholders again.
- Secret sources include host environment values,
systemd-creds, and reviewed shell commands. A command source runs with the invoking user’s privileges. - Captured outbound traffic and exported HAR files can contain real secrets after injection. Inbound captures can contain personal data, prompts, and model output.
Strengths
- Combines network isolation, domain policy, payload inspection, credential brokering, rate limits, and audit logs.
- Offers both convenient containers and stronger VM boundaries through one interface.
- Keeps supported credentials outside the agent workload.
- Inspects WebSocket frames and inbound published-port traffic, not only initial HTTP requests.
- Fail-closed network design limits accidental bypass when a component fails.
- Explicit threat model documents what is and is not defended.
Limits and Risks
- Container mode shares the host kernel; kernel and container-runtime escapes are out of scope.
- Allowed domains remain exfiltration paths through issue text, searches, package metadata, or DNS labels.
- An agent can split a secret across many small requests to evade request-by-request scanners.
- Non-HTTP protocols are blocked unless permitted, but are not content-inspected when passed through.
- Side channels, timing leaks, agent intent, memory poisoning, and confused-deputy use of legitimate allowed APIs are out of scope.
- TLS interception may conflict with certificate pinning or tools that use their own trust store.
- Allowlisted package registries can deliver compromised dependencies with access to the agent workspace.
- Nested containers weaken hardening and require special network behavior to remain inspected.
- Traffic captures create a new sensitive artifact that needs secure handling.
Activity and Maturity
- Repository created 2026-02-17.
- Latest release: v0.29.0, published 2026-06-30.
- GitHub showed 19 stars, 2 forks, and repository activity through 2026-07-08.
- Ten releases from v0.25.0 through v0.29.0 landed between June 16 and June 30, showing active iteration.
- The README labels the project experimental and unaudited. Version
0.x, small adoption, and rapid releases indicate a changing pre-stable tool. - The security model was last marked reviewed on 2026-05-28.
Best Fit
- Developers who need local agents to call selected APIs without receiving the real API keys.
- Agent workloads where exfiltration control and an inspectable audit trail matter.
- Linux or macOS users who want one policy model across container and VM isolation.
- Persistent agent services such as OpenClaw, or short-lived Claude, Codex, and Pi sessions.
It is not sufficient alone for adversarial high-assurance use, protection against all covert channels, or environments requiring an audited security product.
Comparison Facts
| Fact | Agentcage | Clawk |
|---|---|---|
| Main focus | Inspected network and secret isolation | Disposable coding-agent VM workflow |
| Isolation | Container, Lima VM, or Apple microVM | Platform-specific local VM |
| Network | No direct gateway; TLS proxy, DNS policy, inspectors | Userspace domain allowlist before outbound dialing |
| Credentials | Placeholder injection from separate egress sibling | Agent credentials placed within project VM workflow |
| Payload inspection | HTTP, WebSocket, DNS, secret and entropy checks | Domain-level network filtering; no comparable payload scanner documented in HN |
| Persistence | Ephemeral or persistent cages | Disposable VMs with suspend/resume |
| Complexity | Two-role topology plus policy and certificate handling | Direct VM orchestration and forwarding |
Agentcage provides deeper egress inspection and credential brokering. Clawk provides a focused local VM experience with fewer moving parts.
Hacker News Context
In the Clawk discussion, Agentcage author lucamartinetti described it as another tool offering a choice between a container and a VM, with a man-in-the-middle proxy on top. This is accurate but abbreviated: the repository documents three backends and a broader chain of DNS filtering, payload inspection, secret injection, rate limits, and auditing.
The HN comment is a maintainer disclosure, not independent security validation.
Unknowns
- Independent penetration testing, professional audit results, and production incident history.
- Long-term maintenance and compatibility guarantees.
- Performance overhead for TLS interception and inspectors under real agent workloads.
- Behavior with applications using certificate pinning, unusual DNS, or non-HTTP protocols.
- Native Windows plans.