# Isolation tiers

> The tiers of agent isolation in agentjail: hooks, the OS-native sandbox, and planned kernel-level enforcement.

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](/docs/concepts/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 `--netproxy` egress 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](/docs/concepts/how-it-works): details on the Tier 1 hook
  architecture.
- [OS-native sandbox](/docs/concepts/sandbox): the full Tier 1.5 guide.
- [Safely skipping permission prompts](/docs/guides/skip-permissions): a
  practical guide to running agents with the sandbox.