Berry Wiki

AgentJail

Properties2
tagsai, sandboxing
aliasesAgentjail

7 min read

AgentJail

Summary

AgentJail adds policy checks and an optional operating-system sandbox around Claude Code, Codex, and Cursor. It combines pre-tool-call decisions, Open Policy Agent rules, audit history, file restrictions, credential stripping, and opt-in per-host network filtering.

  • Repository: LuD1161/agentjail
  • Implementation: Go and Rego policy
  • License: Apache-2.0
  • Latest release: v0.8.2
  • Checked: 2026-07-14

Problem

Coding agents can run destructive commands, read credentials, contact unexpected services, or call powerful external tools. AgentJail aims to block predictable mistakes before execution and contain bypasses made through shell children or downloaded programs.

How It Works

Two layers complement each other:

  • Policy hook: Agent tool calls pass through a local hook to a persistent daemon. Open Policy Agent rules return allow, ask, or deny.
  • Shield: agentjail-shield starts the agent inside a native OS sandbox. Child processes inherit its file and network restrictions.

Shipped supporting features include SQLite decision logs, session replay, MCP server/tool policy, custom Rego rules, trusted per-project policy overlays, runtime host-access requests, policy self-protection, environment credential stripping, and a local review interface.

Security Boundary

  • macOS: Apple Seatbelt through sandbox-exec; its filesystem design is allow-by-default with explicit sensitive-path denies.
  • Linux: Landlock allow-list rules; sensitive home directories are omitted and restrictions cannot be removed by descendants.
  • Network proxy: With --netproxy, a session token selects a per-session hostname allow-list. The control socket is hidden from the agent.
  • Hook policy: Catches command intent, file-tool requests, and MCP calls, but can be bypassed by operations not represented in a checked tool call. The shield covers many subprocess bypasses.

Important limits:

  • Both systems share the host kernel.
  • macOS keychain access is allowed for provider login; the hook is expected to stop direct tool reads but subprocess behavior deserves caution.
  • Unsupported platforms run without the shield after a warning.
  • The daemon-unreachable hook default is fail-open. The recommended degraded mode blocks only a small offline set; strict users must select deny.
  • The default shield network mode permits TCP ports 80 and 443 to any destination. Per-host enforcement requires --netproxy.
  • On Linux before kernel 6.7, Landlock cannot enforce network connections, so network remains unrestricted unless another layer is used.

Platforms And Agents

  • macOS: Supported with Seatbelt and launchd.
  • Linux: Supported with Landlock and a systemd user service; kernel 5.13 or later is required for filesystem enforcement.
  • Windows: Deferred. WSL is suggested as a workaround.
  • Agents: Claude Code, Codex, and Cursor are auto-detected and wired.
  • Other commands: The shield can manually wrap any command, but full hook integration is not claimed for every agent.

Setup

Official installation options are a shell installer or Homebrew. Installation detects supported agents, writes their hooks, and starts the daemon. Users should then verify status and run a non-executing policy check.

The shield can be run directly around an agent. --netproxy enables hostname filtering; --audit-strict refuses launch on critical environment findings. Policies live under the AgentJail home and can be extended with validated Rego files.

Auto-update is enabled by default, checks roughly every six hours, verifies update signature and checksum, replaces binaries, and restarts the daemon. It can be disabled.

Network And Credentials

  • Default network: Port-only outbound access on 80 and 443; not a hostname allow-list.
  • Opt-in proxy: --netproxy enforces essential, MCP-derived, and editable hostname tiers per session.
  • Runtime grants: An agent can request a host. Only an unsandboxed human control socket can approve it.
  • SSH: Private key files remain denied, while a forwarded SSH agent can sign. Git receives an agent-focused SSH override unless the user opts out.
  • Environment: Common cloud, database, GitHub, Anthropic, and OpenAI credential variables are stripped by default.
  • Secrets broker: Shipped as part of the shield tier, though exact supported services and residual exposure depend on configuration.
  • Metadata risk: Port-only mode may reach cloud instance metadata. AgentJail warns, records an event, and can refuse launch in strict mode; netproxy blocks it unless allowed.

Strengths

  • Defense in depth: Human-readable policy decisions plus kernel-enforced child-process restrictions.
  • Useful policy language: Rego supports structured, testable rules beyond simple command patterns.
  • MCP awareness: Unknown or sensitive MCP integrations can be blocked or require approval.
  • Self-protection: Some rules prevent agents from modifying AgentJail policy, binaries, or daemon state.
  • Scoped live grants: Agents can ask for network access without approving their own request.
  • Auditability: Decisions are stored and replayable.
  • Fast path: The project reports about 8 ms median hook decisions without a VM boot.

Limits

  • Unsafe defaults for high assurance: Hook failure and unsupported shield platforms fail open; hostname filtering is off by default.
  • macOS deny-list: Unknown sensitive paths may remain visible because the sandbox is not filesystem allow-list based.
  • Kernel version gaps: Older Linux versions lack some file and all Landlock network protections.
  • Approval and policy complexity: Hooks, Rego, shield rules, project overlays, proxy tiers, and agent-native permissions can be hard to reason about together.
  • Provider essentials cannot be removed: Required agent and allowed-MCP hosts remain reachable under the proxy.
  • Host remains writable where allowed: This is not a disposable machine.
  • Young project: No independent security audit was found.

Shipped Versus Planned

Shipped: Tool hooks, policy daemon, built-in and custom Rego rules, macOS/Linux shield, environment stripping, secrets broker, session-aware hostname proxy, runtime host grants, MCP scanning/policy, logs, replay, and local UI.

Not yet established as shipped:

  • The HN author described an HTTP-aware policy language for matching host, method, and path. Current docs establish hostname CONNECT filtering, not method/path enforcement.
  • A transparent tunnel intended to replace proxy environment variables is planned.
  • Hardware-isolated microVM support is proposed with early experiments.
  • eBPF LSM and macOS System Extension enforcement are planned.
  • Native Windows support is deferred.

Activity And Maturity

Checked 2026-07-14:

  • Created: 2026-06-04.
  • Latest release: v0.8.2, published 2026-07-14.
  • Latest checked commit: eb9bcca243a1, dated 2026-07-14.
  • History: About 466 commits and more than 20 releases.
  • Interest: 60 stars and 2 forks.
  • Assessment: Very active and feature-rich for its age, but still pre-1.0 with rapidly changing security behavior.

Best Fit

Best for a macOS or modern Linux developer who wants policy-based protection around existing local agents without moving work into a VM.

High-assurance users should enable netproxy, strict daemon-unreachable behavior, and strict launch audit. Use a VM for hostile code, stronger kernel separation, or simpler containment reasoning.

Comparison

  • Versus Clawk: AgentJail preserves the host environment and adds rich intent policy. Clawk gives the agent a disposable separate kernel with network restriction as a core boundary.
  • Versus Pi Landstrip: Both use native OS controls. AgentJail adds OPA command/MCP policy, audit, and several agent integrations; Pi Landstrip has an integrated interactive resource-grant flow for Pi.
  • Versus Flar: Flar uses Bubblewrap on Linux with a small project-only view. AgentJail spans macOS/Linux and adds tool intent policy, but has more moving parts and more permissive defaults.
  • Versus agent permission prompts: AgentJail enforces external policy and can cover child processes through the shield.

HN Context

The author introduced AgentJail as OS-native sandboxing plus Open Policy Agent rules, with a protocol-aware proxy “coming soon.” A commenter asked whether it classified commands into deny, ask, and approve tiers.

The author rejected probabilistic command classification as the security boundary. They described deterministic OS path protection and proposed a request-aware policy language that could distinguish operations such as GitHub reads from writes or Kubernetes deletes.

As of this check, the repository has advanced beyond that HN post: a session-aware hostname proxy is shipped. However, the richer request method/path policy shown in the comment is still not evidenced as a released feature.

Unknowns

  • Audit: No independent penetration test or formal review was found.
  • Protocol proxy: Delivery plan for method/path-aware filtering is unclear.
  • Keychain exposure: The practical boundary around provider refresh and other keychain items needs adversarial testing.
  • Agent hook parity: Exact coverage differences between Claude Code, Codex, and Cursor were not summarized in one compatibility table.
  • Telemetry backend: Data fields are documented, but retention and server-side handling were not assessed here.

Sources

Graph View