Skip to content
ai-jail
EnglishPortuguês (Brasil)Españolעברית日本語한국어
Menu
Do I need it?What an agent can reach on your machineHow it worksThe layers between the agent and your systemCompareBuilt-in sandboxes, Docker and VMsConfigureOpen only what a task needsSecurityThe threat model and its limitsInstall
Install

Install it, look inside, run your agent

ai-jail is one program with no daemon and no root. You install it, put its name in front of the command you already type, and the agent starts inside a sandbox.

Pick an install methodGitHub releases

Install

Choose the way you already install command line tools. Every method gives you the same single ai-jail program.

terminal
brew tap akitaonrails/tap && brew install ai-jail

Works on macOS and on Linux.

What your system needs

Linux

Install bubblewrap, the small program ai-jail uses to build the sandbox. Most distributions package it as bubblewrap.

terminal
pacman -S bubblewrapapt install bubblewrapdnf install bubblewrap

macOS

Nothing to install. ai-jail uses sandbox-exec, which ships with macOS. Apple marks that interface as deprecated.

Windows

Not supported. Use WSL2 and follow the Linux steps inside it.

Your first run

Three commands take you from a plan, to a look inside, to a working agent. ai-jail opens nothing until you ask.

Three panels from left to right. Dry run: the cell is only a dashed outline and the agent waits outside. Look around: the cell is solid and holds a terminal and the project folder. Run the agent: the agent and the project are inside, with two openings in the wall, one for the network and one for the agent's login. Your home folder stays barred outside in all three.
Your home directory stays outside at every step. Only the last step opens anything, and only the two things a cloud agent needs.

  1. See the plan without running anything

    Go to your project and ask for a dry run. ai-jail prints the sandbox command it would use and exits. A dry run never writes a file.

    dry run
    cd ~/Projects/my-appai-jail --dry-run claude

  2. Look around inside

    Start a plain shell in the jail. Your project is there at its real path and you can edit it. Your home directory is a fresh, empty one, and your shell's tokens are gone. Type exit to leave.

    a shell in the jail
    ai-jail bash

  3. Run the agent with the two things it needs

    An agent that talks to a cloud model needs the network to reach it, and its own saved login to prove who you are. Both are off by default, so you turn them on: --network and --agent-state. Since version 1.22, ai-jail prints a warning naming the missing flag if you start a known agent without one of them.

    the real run
    ai-jail --network --agent-state claude

  4. Make it the default for that agent

    Put the two settings in ~/.ai-jail, your own config file, under the agent's name. After that the short command is enough. The .ai-jail file that may appear in the project can only tighten the jail. It can never turn the network or a login on, so a repository you clone cannot open the jail for itself.

    ~/.ai-jail
    [commands.claude]network = trueagent_state = true # from now on, in any project:# ai-jail claude

What you will see inside

The prompt changes to (jail) and the project is where it always was. The things worth stealing are missing.

ai-jail bash, on Linux
$ ai-jail bash# the project is at its real path(jail) ~/Projects/my-app $ pwd/home/you/Projects/my-app# a token exported in your shell did not come along(jail) ~/Projects/my-app $ echo $GITHUB_TOKEN # your keys are not in this home(jail) ~/Projects/my-app $ cat ~/.ssh/id_ed25519cat: /home/you/.ssh/id_ed25519: No such file or directory# the jail has its own hostname(jail) ~/Projects/my-app $ hostnameai-sandbox

This is a Linux session. macOS has no way to build a separate file tree, so there the same paths exist and reading them is refused.

The view from inside the cell. The agent sits next to a large, bright project folder, with an empty home and the system tools behind it. Outside the bars, dim and barred: SSH keys, cloud logins, other projects and the network.

From inside, the project is the only thing of yours that exists. The network stays outside too until you pass --network.

If it does not start

These are the cases the README's troubleshooting covers, plus the two setup rules people trip on.

bwrap: setting up uid map: Permission denied

Ubuntu 24.04 and later and Debian 13 and later ship an AppArmor policy that stops programs from creating user namespaces without root, which is how bubblewrap isolates the jail. It affects every rootless tool of this kind. Relax it for the whole system:

terminal
echo 'kernel.apparmor_restrict_unprivileged_userns=0' \  | sudo tee /etc/sysctl.d/60-userns.confsudo sysctl --system

Or keep the policy and exempt only bwrap. Save this as /etc/apparmor.d/bwrap, then run sudo apparmor_parser -r /etc/apparmor.d/bwrap.

/etc/apparmor.d/bwrap
abi <abi/4.0>,include <tunables/global>profile bwrap /usr/bin/bwrap flags=(unconfined) {  userns,}

Your BWRAP_BIN is refused

You can point ai-jail at a specific bubblewrap with BWRAP_BIN. ai-jail accepts it only when it resolves to a program owned by root that other users cannot write, or to one in a standard multi-user /nix/store. It refuses a copy in your own home, because anyone who can replace that file controls the jail.

mise tools are missing inside

ai-jail activates mise when it finds it, but the fresh home has neither mise's config nor its installed tools, so it skips activation. Map both in, read only, from your own config:

~/.ai-jail
[commands.claude]ro_maps = ["~/.config/mise", "~/.local/share/mise"]

Failed to create stream fd at startup

This comes from a login script on Ubuntu desktop during mise setup. It is harmless and mise still works. Pass --no-mise to skip mise setup and the message with it.

terminal
ai-jail --no-mise claude

Per agent

ai-jail knows where each agent keeps its login. --agent-state mounts only the folders of the agent you start, and only if they exist.

You run--agent-state mountsGood to know
ai-jail claude~/.claude
~/.claude.json		For a second Claude profile, point --claude-dir at its directory.
ai-jail codex~/.codexAfter you resize the window, ai-jail sends Codex a redraw key so the screen repaints.
ai-jail opencode~/.config/opencode
~/.local/share/opencode
ai-jail gemini~/.gemini
ai-jail ai-memory run claudeThe launched agent's foldersai-jail recognizes the agent that ai-memory launches and applies that agent's settings, with both programs in one jail.

The same works for crush, grok, jcode, pi, aider, soulforge, omp and the kimi commands. Any other command runs too. It gets the same jail and no login folder.

Keep reading

Configure

Every flag and config key, and how to open only what a task needs.

How it works

The layers between the agent and your system, on Linux and on macOS.

Security

What ai-jail stops, what it does not, and how releases are signed.

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.

terminal
brew tap akitaonrails/tap && brew install ai-jailai-jail claude
Install ai-jailView on GitHub