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.
What happens at launch
It takes a moment, every time, and nothing keeps running in the background afterwards.
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.
It builds the sandbox
ai-jail sets up each layer below before the agent exists. 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.
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.
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 no network unless you pass--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. - What it stops
~/.ssh,~/.aws,~/.gnupg,~/.dockerand browser profiles are on a built-in list that is never mounted. 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 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, the call that types keystrokes into a terminal. It is a blocklist on purpose, so compilers and runtimes keep working.
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. You pass 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.
| 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 | Off by default, in its own network namespace | Off by default. In lockdown it is always blocked, even with --network. |
| 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
- 8
- direct dependencies
- 720
- unit tests in the source
- 19
- tests that try to escape a real sandbox
Counted in the ai-jail repository at version 1.22.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