It reads your rules
ai-jail trusts your own ~/.ai-jail file. It treats a .ai-jail file inside the project as untrusted: that file can tighten the sandbox but never open it. Flags on the command line win over both.
How it works
What happens when you type ai-jail claude
ai-jail builds a small, closed copy of your system, puts your project in it, and starts the agent inside. The walls are features of the operating system itself, so the agent runs at full speed and cannot switch them off. Per launch, the network is closed apart from the agent's own API host, open to a few named hosts, or fully open.
For the engineer who wants to know what is enforced. The first paragraph and the first picture are enough for everyone else.
What happens at launch
It takes a moment, every time, and nothing keeps running in the background afterwards.
↔ Swipe sideways to see the full diagram
It builds the sandbox
ai-jail sets up each layer below before the agent exists, and maps the toolchains you have (mise, cargo, npm and other caches) read-only or into a jail-owned cache. If a config file is unreadable or invalid, ai-jail stops instead of starting with weaker rules.
It starts the agent inside
The agent, and every script, package and MCP server it starts, inherits the same walls. When the agent exits, ai-jail exits too.
Three ways to the network
Every launch picks one of three network modes. The default is the strictest: no route out except what the filtered proxy lets through, which is a known agent's own API host on both platforms and, on Linux with toolchains on (the default), a short list of package registries. The other two are flags you pass on purpose.
↔ Swipe sideways to see the full diagram
Off
The default. The sandbox gets a private network namespace with no route out, except through the filtered proxy. For a known agent the proxy lets its own API host through, on Linux and macOS, so a bare ai-jail claude works. On Linux, with toolchains on (the default), it also lets a fixed list of package registries through, so npm install and cargo build work; on macOS the registries stay closed. --no-network makes it fully offline.
Filtered
--allow-host HOST, repeatable. The namespace stays closed; a small bridge inside forwards traffic to a CONNECT proxy outside, which dials only the listed hosts and their subdomains. The proxy resolves each name once, outside, and dials the address it checked. ai-jail sets http_proxy inside, and a program that ignores it reaches nothing.
Open
--network. The wall is gone on the network side, and the agent can send out whatever it can read.
| Linux | macOS | |
|---|---|---|
| The fence in filtered mode | The network namespace itself, plus the bridge inside it | One sandbox-exec rule that allows outbound connections to the proxy's port only |
| DNS inside the sandbox | Fails. The proxy resolves names outside. | The system resolver is not fenced, so a low-bandwidth DNS channel remains |
The layers, from the outside in
ai-jail does not trust any single wall to hold alone. On Linux the agent sits behind five of them, each enforced by the kernel, plus two filters on what goes in and what comes out.
↔ Swipe sideways to see the full diagram
Namespaces
bubblewrap- What it is
- A namespace is the kernel giving a process its own private view of the system. ai-jail asks bubblewrap to create them, the same small tool Flatpak uses to sandbox desktop apps, and it needs no root.
- What it stops
- The agent gets its own process list, its own hostname (
ai-sandbox), no inter-process channels to host programs, and a network namespace with no route out unless you open one with--allow-hostor--network. If ai-jail dies, everything inside dies with it.
Filesystem
mounts- What it is
- Inside the namespace, only what ai-jail mounts exists. The project is read-write at its real path, system directories such as
/usrare read-only, and the home directory and/tmpare fresh and held in memory. The toolchains you have (mise, cargo, npm caches) are mapped into that fresh home, read-only or as a jail-owned cache. - What it stops
~/.ssh,~/.aws,~/.gnupg,~/.dockerand browser profiles are on a built-in list that is never mounted. The harness's own state directory, for example Claude's~/.claude, is the exception: ai-jail mounts it read-write by default so the agent starts logged in, and--no-agent-stateleaves it out. Anything written outside the project vanishes when the session ends.
Landlock
kernel 5.13+- What it is
- Landlock is a Linux kernel feature that lets a process give up access to files for good. ai-jail uses it to repeat the filesystem rules as a second allowlist inside the kernel.
- What it stops
- A mistake or a trick in the mount layer is not enough to reach a path outside the list, and read-only stays read-only. On kernels 6.12 and newer it also scopes abstract Unix sockets and signals, best effort. On kernels too old for Landlock, ai-jail says so and continues with the other layers.
seccomp
system calls- What it is
- Programs ask the kernel for things through system calls. seccomp is a filter on those calls, and ai-jail uses it to refuse the ones a coding agent never needs.
- What it stops
- The filter blocks
ptrace,mount,bpf, kernel modules,io_uring, the kernel keyring, raw sockets, andTIOCSTI, a call that can type keystrokes into your terminal. It is a blocklist on purpose, so compilers and runtimes keep working. The one process started before Landlock and seccomp apply is the small bridge that carries filtered network traffic out, so it alone stays unrestricted.
Resource limits
rlimits- What it is
- Caps the kernel enforces on how much a process tree may use: 4,096 processes and 65,536 open files, with core dumps turned off. Lockdown mode lowers them to 1,024 and 4,096.
- What it stops
- A fork bomb or a runaway script hits the ceiling inside the jail instead of freezing your machine. The agent cannot raise the limits again.
Environment allowlist
what goes in- What it is
- Your shell is full of variables, and some of them are API keys. ai-jail clears the environment and passes only a short list:
PATH,HOME,TERM, locale, proxy and certificate settings. - What it stops
- Tokens and cloud credentials exported in your shell never reach the agent, except the invoked harness's own API key, for example
ANTHROPIC_API_KEYfor Claude, which is copied by default along with its login;--no-agent-statestops it. You pass another one through by name with--envwhen a task needs it.
Terminal proxy
what comes out- What it is
- The agent runs behind its own pseudo-terminal, and what it prints passes through a terminal parser before it reaches your screen. The same proxy draws the ai-jail status bar on the bottom row.
- What it stops
- The proxy filters out escape sequences that touch your clipboard or query your terminal. Inside tmux or zellij it turns itself off, because nested terminals fight over resizing.
On macOS the wall is thinner
macOS has no namespaces, Landlock or seccomp. ai-jail turns the same policy into a profile for sandbox-exec, Apple's built-in sandbox. The ai-jail documentation says plainly that this is not equivalent to the Linux isolation.
↔ Swipe sideways to see the full diagram
| Linux | macOS | |
|---|---|---|
| Backend | bubblewrap, then Landlock, seccomp and resource limits | sandbox-exec with a profile generated for each launch. Apple has deprecated it, and nothing better exists without kernel extensions. |
| Home directory | A fresh in-memory home. Your real one is not mounted. | The profile starts with no global reads and then allows only the paths the agent needs, so your real home stays closed. |
/tmp | Private, discarded on exit | The host's /tmp, because there is no mount namespace. TMPDIR points at a private folder made for the launch, and that is the only temp path granted. |
| Copy-on-write maps | --overlay-map lets the agent write to a copy | Treated as a read-only map |
| Network | Closed by default: no route out except a known agent's own API host and the package registries allowed when toolchains are on. --allow-host or --network opens more, --forward-port relays one port of the host's loopback, --no-network closes all. Under --lockdown the open network is always blocked, even with --network. | The same default and the same flags, including the known agent's API host, but without --forward-port, the registries or the toolchain cache maps, which are Linux only. Lockdown blocks the open network here too. |
| Other programs | Invisible: own process list, no host IPC | Mach, IOKit and host IPC are denied unless you pass --macos-host-ipc |
Why these building blocks
ai-jail writes as little security code of its own as it can. It drives bubblewrap, which is small, packaged by every major distribution and exercised daily by Flatpak, and adds kernel features on top.
| Option | Why not |
|---|---|
| Firejail | It can do the job, but it is a setuid root binary, and several CVEs come from that design. bubblewrap works without root. |
| Rewriting bubblewrap in Rust | More than 500 lines of security-sensitive code to maintain and patch alone, to avoid a dependency of about 50 KB that receives upstream fixes. |
| nsjail | Capable, but built for servers and driven by protobuf config files, and less widely packaged. |
| systemd-nspawn | Requires systemd, so it fails inside containers and on systems without it. |
Small enough to read
The whole tool is one synchronous Rust program, with no async runtime, daemon or container image.
- 1
- binary to install
- 11
- direct dependencies
- 959
- unit tests in the source
- 23
- tests that try to escape a real sandbox
Dependencies counted in the ai-jail repository at version 2.9.0; tests at version 2.9.0.
Put your agent behind bars
ai-jail is a single binary that needs no daemon and no root. You add one word in front of the command you already run.
brew tap akitaonrails/tap && brew install ai-jailai-jail claude