agentjail is designed across three levels of isolation strength. They are not mutually exclusive: stronger tiers layer on top of lighter ones for defense in depth.
Tier 1: Hooks (lightest)
The agent runs normally on the host. agentjail intercepts at the agent’s own
tool-call boundary using the platform hook system (PreToolUse for Claude Code
and Codex, preToolUse + beforeShellExecution for Cursor). No changes to
the host OS, no container, no kernel module required.
What you get:
- Zero friction to install; hooks are a first-class feature of all supported agents.
- Policy decisions happen in user space, in the host shell.
- An agent that cooperates with its hook framework cannot bypass this layer.
- Three verdict types: allow, ask (prompt the user), and deny.
Limitation: Does not protect against agents that skip hook dispatch, or
shell tricks like eval, variable expansion, and non-shell interpreters
(python -c, osascript) that bypass pattern matching.
This is what agentjail install sets up by default.
Tier 1.5: OS-native sandbox
The OS-native sandbox (agentjail-shield) wraps the
agent in the kernel’s own sandboxing mechanism before exec’ing it. Every
subprocess inherits the restrictions.
What it adds over Tier 1:
- Kernel-level enforcement. Shell tricks,
eval, and subprocess spawns that bypass the hook layer are caught at the syscall boundary. - Network capture and egress control. The agent’s traffic runs through
agentjail’s transparent tunnel + MITM on both Linux and macOS - including the
LLM provider call, captured on macOS with no system extension via a base-URL
capture gateway. (The older
--netproxyegress firewall still works but is deprecated in favor of the tunnel.) - No privileges required. Uses Apple Seatbelt on macOS and Landlock on Linux, both running as the invoking user.
Limitation: Seatbelt and Landlock are filesystem/exec sandboxes, not full syscall interposition; network capture and enforcement come from the tunnel layer on top, not the LSM itself.
Tier 2: Kernel-level enforcement (planned, strongest)
Planned, not shipped. A kernel-level layer (eBPF LSM on Linux, a macOS system extension) would intercept file, network, and process events system-wide, regardless of whether the agent runs directly on the host.
What it would add over the sandbox:
- Covers any process on the machine, not only agents that agentjail spawned.
- No agent cooperation required: works even if the agent binary is replaced or modified.
- Suitable for fleet-wide deployment where every machine needs a consistent enforcement boundary.
Choosing a tier
| Tier | Setup effort | Protection scope | When to use |
|---|---|---|---|
| 1: Hooks | One command | Tool calls only | Default for daily development |
| 1.5: Sandbox | One command | Tool calls + shell tricks + subprocesses + network capture | When you run agents with permissions disabled |
| 2: Kernel-level (planned) | Kernel/extension install | System-wide | Enterprise fleet enforcement |
Most users start at Tier 1 and add Tier 1.5 when they want to safely skip permission prompts. Tier 2 (kernel-level, planned) is for fleet-wide enforcement of every process, not just agents agentjail spawned.
Next steps
- How it works: details on the Tier 1 hook architecture.
- OS-native sandbox: the full Tier 1.5 guide.
- Safely skipping permission prompts: a practical guide to running agents with the sandbox.