← All docs

Installation

Install agentjail and wire it into your coding agent in under a minute.

agentjail installs a set of binaries plus a default policy bundle. The install script detects your platform and drops everything into place.

Platform note: agentjail install works on macOS and Linux (both first-class today; Windows is deferred - WSL works in the meantime). Claude Code, Codex, and Cursor are all supported: the installer auto-detects whichever agents are present on the machine. On Linux, the daemon runs as a systemd user service instead of a launchd plist.

Install

curl -fsSL https://agentjail.io/install.sh | sh

This downloads the release tarball for your platform (macOS arm64/amd64, Linux arm64/amd64), verifies the SHA256 checksum, and installs two binaries to ~/.agentjail/bin/:

  • agentjail: the product binary. It runs as its different roles through symlinks - agentjail-daemon (the persistent daemon that keeps OPA warm), agentjail-shield (the OS sandbox), agentjail-netproxy, agentjail-secrets.
  • agentjail-hook: the tiny binary each agent’s PreToolUse hook calls

The macOS tarball does not include or activate the separately built Network Extension application used by the full transparent tunnel. Default provider capture still works without it. See the sandbox network model for the boundary.

Alternatively, if you use Homebrew:

brew install LuD1161/tap/agentjail

Verify

agentjail version
agentjail policy list

The first command confirms the binary is on your PATH; the second prints the policies that are currently active.

Wire it into your coding agents

Run the install command to register the daemon and hook:

agentjail install

This presents an interactive multi-select picker of all detected agents (Claude Code, Codex, Cursor). Press Enter to wire them all, or Space to deselect agents you want to skip. Without a TTY (CI), all detected agents are wired automatically.

To wire a single agent:

agentjail install --for claude-code   # or codex / cursor
agentjail install --all               # non-interactive, wire all detected

Two opt-in flags harden the install further. --with-path-shim puts wrappers for claude, codex, and Cursor’s agent command first on PATH, so the commands you already type enter the OS sandbox and transparent tunnel. Child arguments pass through unchanged. --with-apparmor (Linux only) loads a scoped userns AppArmor profile for the sandbox, prompting for sudo once. See the CLI reference for full flag semantics.

The PATH-shim choice is sticky. Its shell-profile marker records consent, and reinstall, agentjail update, and daemon auto-update regenerate the complete wrapper set. Updates never opt in a user who did not request it.

The installer:

  1. Starts agentjail-daemon (via launchctl on macOS; systemd user service on Linux) and writes the default ~/.agentjail/policy.yaml.

  2. Writes a PreToolUse hook entry into each agent’s settings file (e.g. ~/.claude/settings.json for Claude Code):

    {
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "~/.agentjail/bin/agentjail-hook" }]
      }
    ]
  }
}

  3. Seeds mcp.allowed from MCP servers already configured in your agents, so existing servers keep working immediately.

From this point on, every tool call the agent is about to make passes through agentjail-hook, which forwards it to the daemon for policy evaluation in ~8 ms median. Allowed calls run as normal; denied calls never reach the shell.

Next: run it shielded

Wiring the hook guards every tool call. To also get the OS-native sandbox (Seatbelt/Landlock) and network visibility - capturing exactly what your agent sends its model - launch your agent through agentjail:

agentjail claude                # Claude Code
agentjail run -- codex          # Codex
agentjail run -- cursor         # Cursor

See the OS-native sandbox for the sandbox and network capture model, and isolation tiers for how the layers fit together.