ai-jail

A sandbox wrapper for AI coding agents (Linux: bwrap, macOS: sandbox-exec). Isolates tools like Claude Code, GPT Codex, OpenCode, and Crush so they can only access what you explicitly allow.

Install

Homebrew (macOS / Linux)

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

cargo install

cargo install ai-jail

mise

mise use -g github:akitaonrails/ai-jail

Nix (flake)

# Run directly without installing
nix run github:akitaonrails/ai-jail

# Install to your profile
nix profile install github:akitaonrails/ai-jail

GitHub Releases

Download prebuilt binaries from the Releases page:

# Linux x86_64
curl -fsSL https://github.com/akitaonrails/ai-jail/releases/latest/download/ai-jail-linux-x86_64.tar.gz | tar xz
sudo mv ai-jail /usr/local/bin/

# macOS ARM (Apple Silicon)
curl -fsSL https://github.com/akitaonrails/ai-jail/releases/latest/download/ai-jail-macos-aarch64.tar.gz | tar xz
sudo mv ai-jail /usr/local/bin/

From source

cargo build --release
cp target/release/ai-jail ~/.local/bin/

Dependencies

Linux: bubblewrap (bwrap) must be installed:
- Arch: pacman -S bubblewrap
- Debian/Ubuntu: apt install bubblewrap
- Fedora: dnf install bubblewrap
- If bwrap is in a non-standard location (e.g. Nix store), set BWRAP_BIN=/absolute/path/to/bwrap.
- The Nix flake package already sets BWRAP_BIN automatically.
macOS: /usr/bin/sandbox-exec is used (legacy/deprecated Apple interface).

Ubuntu 24.04+ / Debian 13+ users

These distros ship an AppArmor policy that denies unprivileged user namespace creation, which is how bwrap isolates the sandbox. If ai-jail fails with bwrap: setting up uid map: Permission denied, you need to either relax the system-wide restriction or install a local AppArmor profile for bwrap. This affects every tool that uses rootless user namespaces (Distrobox, rootless Podman, Flatpak from non-standard paths, etc.), not just ai-jail.

Option A — relax the restriction system-wide (simplest):

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

Option B — install an unconfined profile for bwrap only (keeps the rest of the policy intact):

sudo tee /etc/apparmor.d/bwrap >/dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>
profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
sudo systemctl reload apparmor

Pick whichever matches your threat model. We don't ship a profile with ai-jail itself because the profile has to apply to bwrap, which is system-owned.

Quick Start

cd ~/Projects/my-app

# Run Claude Code in a sandbox
ai-jail claude

# Run bash inside the sandbox (for debugging)
ai-jail bash

# See what the sandbox would do without running it
ai-jail --dry-run claude

On first run, ai-jail creates a .ai-jail config file in the current directory by default. Subsequent runs reuse that config. Commit .ai-jail to your repo so the sandbox settings follow the project. Use --no-save-config for ephemeral runs without creating or updating the project config.

If you run ai-jail from a linked Git worktree, it auto-detects the worktree's external Git admin directories and exposes them safely inside the sandbox so git status, git commit, and similar commands keep working. Disable this with --no-worktree or no_worktree = true.

⚠️ The agent can only persist writes to your current project directory. Everything else inside the sandbox (parent directories, sibling directories, $HOME, /tmp) lives in a tmpfs and is wiped when ai-jail exits. If you ask the agent to create files outside the project — for example a sibling scaffold folder, a clone in your home, or anything under ~/.cache — those writes go to RAM and disappear on exit. Push to a remote, copy back into the project dir, or expose extra writable paths with --rw-map ~/path before relying on them. The agent has no way to detect this from inside the sandbox; it sees a fully-writable filesystem.

Security notes

The default mode favors usability over maximum lockdown. These are intentionally open by default:

Docker socket passthrough auto-enables when /var/run/docker.sock exists (--no-docker disables it).
Display passthrough mounts XDG_RUNTIME_DIR on Linux, which can expose host IPC sockets.
Environment variables are inherited (tokens/secrets in your shell env are visible in-jail).

Hiding project-level secrets: the project directory is mounted in its entirety, so files like .env, credentials.json, or secrets.yml are visible to whatever runs inside. Use --mask PATH to replace them with empty files inside the sandbox. Example:

ai-jail --mask .env --mask .env.local claude

Or persist the list in .ai-jail:

mask = [".env", ".env.local", "credentials.json"]

Hiding the sandbox policy itself: by default, ai-jail auto-masks the project's own .ai-jail config file inside the sandbox so the agent can't read its own policy and craft workarounds. Pass --no-hide-config (or set no_hide_config = true) if you need the file visible to the sandboxed process for some reason. The user's global ~/.ai-jail is never mounted into the sandbox.

Private home mode: use --private-home when you want the project writable but do not want normal host dotdirs like ~/.config, ~/.cache, ~/.local, or AI tool state mounted into the sandbox. Explicit mounts still apply. On Linux, this uses a tmpfs $HOME; on macOS, seatbelt rules deny normal host-home reads/writes instead.

ai-jail --private-home claude
ai-jail --private-home --rw-map ~/Downloads/test-data bash

Defense-in-depth layers (Linux)

ai-jail applies multiple overlapping security layers:

Namespace isolation (bwrap): PID, UTS, IPC, mount namespaces. Network namespace in lockdown.
Landlock LSM (V3 filesystem + V4 network): VFS-level access control independent of mount namespaces.
Seccomp-bpf syscall filter: blocks ~30 dangerous syscalls (module loading, ptrace, bpf, namespace escape, etc.). Lockdown blocks additional NUMA/hostname syscalls.
Resource limits: RLIMIT_NPROC (4096/1024 lockdown), RLIMIT_NOFILE (65536/4096 lockdown), RLIMIT_CORE=0. Prevents fork bombs and limits resource abuse.
Sensitive /sys masking: tmpfs overlays hide /sys/firmware, /sys/kernel/security, /sys/kernel/debug, /sys/fs/fuse. Lockdown also masks /sys/module, /sys/devices/virtual/dmi, /sys/class/net.

Each layer can be individually disabled (--no-seccomp, --no-rlimits, --no-landlock) if it causes issues.

For hostile/untrusted workloads, use --lockdown (see below).

What this is and isn't

ai-jail is a thin wrapper around OS-level sandboxing, so its security properties depend on the backend:

bwrap (Linux): namespace + mount sandboxing in userspace, plus Landlock LSM for VFS-level access control (Linux 5.13+).
sandbox-exec / seatbelt (macOS): legacy policy interface to Apple sandbox rules.

Some things to keep in mind:

All backends depend on host kernel correctness. Kernel escapes are out of scope.
These are process sandboxes, not hardware isolation. A VM runs a separate kernel and gives a stronger boundary.
Timing/cache side channels and scheduler interference still exist in process sandboxes.
Linux and macOS primitives are not equivalent; cross-platform policy parity is approximate.
sandbox-exec on macOS is a deprecated interface. It works today but Apple could remove it.

If you need full isolation against unknown malware, use a disposable VM and treat ai-jail as one layer, not the whole story.

Lockdown mode

--lockdown switches to strict read-only, ephemeral behavior for hostile workloads.

ai-jail --lockdown claude

This:

Mounts the project read-only.
Disables GPU, Docker, display passthrough, and mise.
Ignores --rw-map and --map flags.
Mounts $HOME as bare tmpfs (no host dotfiles).
Still exposes validated linked Git worktree metadata read-only when needed, so read-only Git operations can work from linked worktrees.
Linux: --clearenv with minimal allowlist, --unshare-net, --new-session.
macOS: clears env to minimal allowlist, strips network and file-write rules from SBPL profile.

Persistence: --lockdown alone doesn't write .ai-jail (keeps runs ephemeral). Persist it with ai-jail --init --lockdown. Undo with --no-lockdown.

--init always writes config, so it cannot be combined with --no-save-config.

Browser profiles

ai-jail can run browsers in a separate locked-down browser profile. Browser commands are auto-detected for Chromium, Chrome, Brave, Firefox, and LibreWolf, or you can opt in explicitly:

ai-jail chromium              # auto: hard browser profile
ai-jail --browser chromium    # explicit hard profile
ai-jail --browser=soft firefox
ai-jail --no-browser chromium # disable browser auto-profile

Both browser profiles avoid the real host browser profiles. They use a private $HOME, keep the project mounted read-only, skip SSH keys, Docker, linked worktree metadata, extra maps, mise, config auto-save, and the terminal status bar. Display and network stay enabled so the browser can actually open and navigate sites.

Hard profile (--browser / --browser=hard): all browser config, cache, history, cookies, extension state, and sessions live under sandbox tmpfs paths and disappear when the browser exits.
Soft profile (--browser=soft): browser state survives only under ~/.local/share/ai-jail/browsers/<browser>, so future ai-jail browser sessions can keep logins and history without touching ~/.config/chromium, ~/.mozilla, or other real browser profiles.

Chromium-family browsers run with Chromium's internal sandbox disabled inside ai-jail because the Chromium zygote/setuid sandbox does not work reliably through the bwrap/user namespace setup. The containment boundary is ai-jail's bwrap mount/process namespace plus Landlock/seccomp, not Chromium's own sandbox. Browser profiles also disable browser GPU acceleration by default to avoid probing unmapped DRM devices; pass --gpu if you want ai-jail to expose GPU devices and leave Chromium GPU acceleration enabled.

Expected Chromium terminal noise: D-Bus, systemd, UPower, Google Cloud Messaging, and EGL/WebGPU warnings can appear because browser profiles deliberately do not expose the host system bus or full desktop session. These messages are usually harmless if the browser window works. --gpu may add EGL/WebGPU capability warnings; omit --gpu for the quieter default software path.

This is useful for testing suspect extensions or websites without giving them read-write access to your normal home directory or browser profile. It is not an anonymity feature: the browser still has network access, sites can fingerprint it, and anything you log into can identify you.

Desktop launcher

Linux desktop environments can launch Chromium through ai-jail with a normal .desktop file. A ready-to-copy example lives at dist/desktop/ai-jail-chromium.desktop:

[Desktop Entry]
Type=Application
Name=Chromium (ai-jail)
GenericName=Sandboxed Web Browser
Comment=Run Chromium inside ai-jail with an isolated persistent browser profile
Exec=ai-jail-chromium %U
Icon=chromium
Terminal=false
Categories=Network;WebBrowser;
MimeType=text/html;text/xml;application/xhtml+xml;x-scheme-handler/http;x-scheme-handler/https;
Keywords=ai-jail;sandbox;chromium;browser;private;
StartupNotify=true
StartupWMClass=chromium

Install it for your user:

mkdir -p ~/.local/bin
cp dist/desktop/ai-jail-chromium ~/.local/bin/
chmod +x ~/.local/bin/ai-jail-chromium

mkdir -p ~/.local/share/applications
cp dist/desktop/ai-jail-chromium.desktop ~/.local/share/applications/
chmod +x ~/.local/share/applications/ai-jail-chromium.desktop
desktop-file-edit --set-key=Exec \
  --set-value="$HOME/.local/bin/ai-jail-chromium %U" \
  ~/.local/share/applications/ai-jail-chromium.desktop
update-desktop-database ~/.local/share/applications

The wrapper adds ~/.local/share/mise/shims to PATH, so it works when ai-jail is installed through mise and the desktop launcher does not inherit your interactive shell environment. It also launches from ~/.local/share/ai-jail/browser-launcher-cwd so ai-jail does not treat your whole home directory as the browser's project directory.

Change the wrapper command to exec ai-jail --browser=hard chromium "$@" if you want every desktop-launched Chromium session to be throwaway. If your launcher caches applications, restart it after installing; on Omarchy/Walker, run omarchy-restart-walker or log out and back in.

What gets sandboxed

Default behavior (no flags needed)

Resource	Access	Notes
`/usr`, `/etc`, `/opt`, `/sys`	read-only	System binaries and config
`/dev`, `/proc`	device/proc	Standard device and process access
`/tmp`, `/run`	tmpfs	Fresh temp dirs per session
`$HOME`	tmpfs	Empty home, then dotfiles layered on top
Project directory (pwd)	read-write	The whole point
Linked Git worktree metadata	auto passthrough	Validated `.git` gitfile targets are mounted when the current directory is a linked worktree
GPU devices (`/dev/nvidia*`, `/dev/dri`)	device	For GPU-accelerated tools
Docker socket	read-write	If `/var/run/docker.sock` exists
X11/Wayland	passthrough	Display server access
`/dev/shm`	device	Shared memory (Chromium needs this)

In --lockdown, project is mounted read-only and host write mounts are removed. For linked Git worktrees, validated external Git metadata is still exposed read-only unless disabled with --no-worktree.

In browser profile mode, the project is mounted read-only, $HOME is private tmpfs, normal host dotdirs are not mounted, and soft browser state is the only persistent browser-specific write mount.

In --private-home mode, normal host dotdirs are not exposed, but the project remains read-write and explicit --map / --rw-map mounts still work. On Linux this is a private tmpfs $HOME; on macOS it is enforced with seatbelt read/write allowlists because sandbox-exec cannot create a replacement home mount. This is useful for non-agent or experimental workloads where you want normal project access without exposing your real ~/.config, ~/.cache, or tool state.

Home directory handling

Your real $HOME is replaced with a tmpfs. Dotfiles and dotdirs are selectively layered on top:

Pass --private-home or set private_home = true to skip this automatic dotdir layering entirely. --ssh, --pictures, --map, and --rw-map remain explicit opt-ins. On macOS, sandbox-exec does not provide tmpfs mounts, so ai-jail approximates this by denying normal host-home reads and writes.

Never mounted (sensitive data):

.gnupg, .aws, .ssh, .mozilla, .basilisk-dev, .sparrow

Mounted read-write (AI tools and build caches):

.gemini, .claude, .crush, .codex, .aider, .config, .cargo, .cache, .docker

Everything else: mounted read-only.

Hidden behind tmpfs:

~/.config/BraveSoftware, ~/.config/Bitwarden
~/.cache/BraveSoftware, ~/.cache/chromium, ~/.cache/spotify, ~/.cache/nvidia, ~/.cache/mesa_shader_cache, ~/.cache/basilisk-dev

Explicit file mounts:

~/.gitconfig (read-only)
~/.claude.json (read-write)
Validated linked Git worktree admin dirs outside the project tree (auto, same-path passthrough)

Local overrides (read-write):

~/.local/state
~/.local/share/{zoxide,crush,opencode,atuin,mise,yarn,flutter,kotlin,NuGet,pipx,ruby-advisory-db,uv}

Namespace isolation

PID, UTS, and IPC namespaces are isolated. Hostname inside is ai-sandbox. The process dies when the parent exits (--die-with-parent). --new-session is on for non-interactive runs and always in --lockdown. In --lockdown, Linux also unshares network.

Landlock LSM (Linux)

On Linux 5.13+, ai-jail applies Landlock restrictions as defense-in-depth on top of bwrap. Landlock controls what the process can do at the VFS level, independent of mount namespaces. This closes attack vectors that bwrap alone doesn't cover: /proc escape routes, symlink tricks within allowed mounts, and acts as insurance against namespace bugs.

Uses ABI V3 (Linux 6.2+) for filesystem rules with best-effort degradation to V1 on 5.13+ or no-op on older kernels.
On Linux 6.5+, a second V4 ruleset adds network restrictions: lockdown mode denies all TCP bind/connect (defense-in-depth alongside --unshare-net).
Applied after bwrap namespace setup via an internal wrapper, so Landlock sees the final sandbox mount layout.
In --lockdown, Landlock rules are stricter: project is read-only, no home dotdirs, only /tmp is writable, no network.
Disable with --no-landlock if it causes issues with specific tools.

Status bar

Enable a persistent status line on the bottom row of your terminal:

ai-jail -s claude          # dark theme
ai-jail -s=light claude    # light theme

The bar shows the project path, running command, ai-jail version, and a green ↑ when an update is available. It uses a PTY proxy to keep the bar visible even when the child application resets the screen. The preference is stored in $HOME/.ai-jail and persists across sessions.

Why it exists: when you run several AI CLI agents in parallel (one per terminal window / split), it's easy to lose track of which window is bound to which project. The status bar keeps the project path and the running command visible at all times so you can't accidentally paste the wrong context into the wrong agent.

Auto-disabled inside tmux and zellij. Those tools already render a persistent status line and already own the terminal; ai-jail's PTY proxy is redundant and causes conflicts (nested PTYs, resize flicker, lost keyboard-protocol sequences, no Secure Input propagation). When ai-jail detects $TMUX or $ZELLIJ in the environment it silently skips the status bar and takes the direct-spawn path, letting the multiplexer drive the terminal. To force the ai-jail bar on anyway, pass -s explicitly or set no_status_bar = false in ~/.ai-jail.

When running codex through the PTY proxy, ai-jail also injects a redraw key on terminal resize to force the app to repaint at the new width. The default is ctrl-shift-l for codex sessions. In practice, terminals collapse shifted control letters, so ctrl-shift-l and ctrl-l send the same control byte to the app.

Override or disable that global behavior in $HOME/.ai-jail:

status_bar_style = "pastel"
resize_redraw_key = "ctrl-l"
# or:
# resize_redraw_key = "disabled"

mise integration

If mise is found on $PATH, the sandbox automatically runs mise trust && mise activate bash && mise env before your command. This gives AI tools access to project-specific language versions. Disable with --no-mise.

Usage

ai-jail [OPTIONS] [--] [COMMAND [ARGS...]]

Commands

Command	What it does
`gemini`	Run Gemini CLI
`claude`	Run Claude Code
`codex`	Run GPT Codex
`opencode`	Run OpenCode
`crush`	Run Crush
`bash`	Drop into a bash shell
`status`	Show current `.ai-jail` config
Any other	Passed through as the command

If no command is given and no .ai-jail config exists, defaults to bash.

Options

Flag	Description
`--rw-map <PATH>`	Mount PATH read-write (repeatable)
`--map <PATH>`	Mount PATH read-only (repeatable)
`--hide-dotdir <NAME>`	Never bind-mount the named home dotdir into the sandbox (e.g. `.my_secrets`). Leading dot is optional. Repeatable. Cannot hide dotdirs required for tool operation (`.cargo`, `.config`, `.cache`, etc.) — those emit a warning and stay visible.
`--mask <PATH>`	Replace `PATH` inside the sandbox with an empty file (or empty tmpfs if the path is a directory). Relative paths resolve against the project directory. Repeatable. Useful for hiding sensitive files like `.env`, `credentials.json` from AI agents while keeping the rest of the project accessible. Missing paths are skipped with a warning.
`--allow-tcp-port <PORT>`	Permit outbound TCP to PORT in lockdown mode (repeatable). Skips `--unshare-net` and uses Landlock V4 `NetPort` rules to deny everything else. Requires Linux ≥ 6.5; hard-fails otherwise. No effect outside lockdown or on macOS.
`--private-home` / `--no-private-home`	Enable/disable private home mode. Private home skips automatic host dotdir passthrough while leaving the project writable and explicit maps active. Linux uses tmpfs `$HOME`; macOS uses seatbelt allowlists.
`--lockdown` / `--no-lockdown`	Enable/disable strict read-only lockdown mode
`--landlock` / `--no-landlock`	Enable/disable Landlock LSM (Linux 5.13+, default: on)
`--seccomp` / `--no-seccomp`	Enable/disable seccomp syscall filter (Linux, default: on)
`--rlimits` / `--no-rlimits`	Enable/disable resource limits (default: on)
`--gpu` / `--no-gpu`	Enable/disable GPU passthrough
`--docker` / `--no-docker`	Enable/disable Docker socket
`--display` / `--no-display`	Enable/disable X11/Wayland
`--worktree` / `--no-worktree`	Enable/disable linked Git worktree metadata passthrough (default: on)
`--mise` / `--no-mise`	Enable/disable mise integration
`--ssh` / `--no-ssh`	Share `~/.ssh` read-only + forward `SSH_AUTH_SOCK` (default: off)
`--pictures` / `--no-pictures`	Share `~/Pictures` read-only (default: off)
`--browser[=PROFILE]` / `--no-browser`	Enable/disable browser isolation profile. `PROFILE` is `hard` (ephemeral, default) or `soft` (persistent under `~/.local/share/ai-jail/browsers/<browser>`). Common browser commands auto-enable `hard` unless disabled.
`--save-config` / `--no-save-config`	Enable/disable automatic `.ai-jail` writes
`--hide-config` / `--no-hide-config`	Auto-mask the project's `.ai-jail` file inside the sandbox so the agent can't read its own sandbox policy (default: on). Pass `--no-hide-config` to make it visible.
`--claude-dir <PATH>`	Use `PATH` as Claude Code's config directory (sets `CLAUDE_CONFIG_DIR`). Enables multiple independent profiles (e.g. `~/.claude` for work, `~/.claude-personal` for a separate account). Path is bind-mounted read-write inside the sandbox. Leading `~/` is expanded against `$HOME`.
`-s`, `--status-bar[=STYLE]`	Enable persistent status line. `STYLE` is `pastel` (default, random palette per session), `dark`, or `light`
`--no-status-bar`	Disable persistent status line
`--exec`	Direct execution mode (no PTY proxy, no status bar)
`--clean`	Ignore existing config, start fresh
`--dry-run`	Print the bwrap command without executing
`--init`	Create/update config and exit (don't run)
`--bootstrap`	Generate smart permission configs for AI tools
`-v`, `--verbose`	Show detailed mount decisions
`-h`, `--help`	Show help
`-V`, `--version`	Show version

Examples

# Share an extra library directory read-write
ai-jail --rw-map ~/Projects/shared-lib claude

# Read-only access to reference data
ai-jail --map /opt/datasets claude

# No GPU, no Docker, just the basics
ai-jail --no-gpu --no-docker claude

# Disable linked Git worktree passthrough for this run
ai-jail --no-worktree claude

# Run a one-shot command and capture its output
result=$(ai-jail --exec -- my-script.sh --flag1 --flag2)

# Suspicious/untrusted workload mode
ai-jail --lockdown bash

# Writable project, but no automatic host home dotdirs
ai-jail --private-home bash

# See exactly what mounts are being set up
ai-jail --dry-run --verbose claude

# Create config without running
ai-jail --init --no-docker claude

# Allow SSH inside the sandbox (agent forwarding + keys read-only)
ai-jail --ssh claude

# Share ~/Pictures read-only (e.g. for image analysis)
ai-jail --pictures claude

# Run Chromium with an ephemeral browser profile
ai-jail chromium

# Run Firefox with a persistent ai-jail-only browser profile
ai-jail --browser=soft firefox

# Hide .env and other secrets from the agent
ai-jail --mask .env --mask .env.local claude

# Use a separate Claude profile (e.g. work vs personal account)
ai-jail --claude-dir ~/.claude-work --init claude
ai-jail claude   # subsequent runs reuse ~/.claude-work via .ai-jail

# Run without creating/updating .ai-jail
ai-jail --no-save-config claude

# Regenerate config from scratch
ai-jail --clean --init claude

# Pass flags through to the sub-command (after --)
ai-jail -- claude --model opus

Config file (`.ai-jail`)

Created in the project directory on first run. Example:

# ai-jail sandbox configuration
# Edit freely. Regenerate with: ai-jail --clean --init

command = ["claude"]
rw_maps = ["/home/user/Projects/shared-lib"]
ro_maps = []
mask = [".env", ".env.local"]
no_gpu = true
ssh = true
private_home = true
lockdown = true

Merge behavior

When CLI flags and an existing config are both present:

command: CLI replaces config for the current run, but a CLI-passed command is not auto-persisted when the project already has a stored command — so ai-jail codex after ai-jail claude runs codex for that session without rewriting .ai-jail's stored default. Use ai-jail --init <command> to explicitly change the stored command. First-run bootstrap (no stored command yet) still persists the CLI command as the new default.
rw_maps / ro_maps / mask: CLI values are appended (duplicates removed). Paths starting with ~/ or exactly ~ are expanded against $HOME at merge time, so you can write ro_maps = ["~/.bashrc"] in a config file.
Boolean flags: CLI overrides config (--no-gpu sets no_gpu = true)
--save-config / --no-save-config override no_save_config
Config is updated after merge in normal mode when config saving is enabled; lockdown skips auto-save

Available fields

Field	Type	Default	Description
`command`	string array	`["bash"]`	Default command to run inside sandbox. Set by first run or by `--init`; not overwritten when a different command is passed on the CLI.
`rw_maps`	path array	`[]`	Extra read-write mounts
`ro_maps`	path array	`[]`	Extra read-only mounts
`hide_dotdirs`	string array	`[]`	Extra home dotdirs to deny (e.g. `[".my_secrets"]`). Leading dot optional. Built-in deny list (`.ssh`, `.gnupg`, `.aws`, `.mozilla`) always applies.
`mask`	path array	`[]`	Paths to replace with empty files/tmpfs (e.g. `[".env", "secrets.json"]`). Relative paths resolve against the project directory.
`allow_tcp_ports`	u16 array	`[]`	TCP ports permitted outbound in lockdown mode (e.g. `[32000, 8080]`). Requires Linux ≥ 6.5 for Landlock V4. No effect outside lockdown.
`private_home`	bool	not set (off)	`true` skips automatic host dotdir passthrough without enabling full lockdown. Project and explicit maps remain writable. Linux uses tmpfs `$HOME`; macOS uses seatbelt allowlists.
`no_gpu`	bool	not set (auto)	`true` disables GPU passthrough
`no_docker`	bool	not set (auto)	`true` disables Docker socket
`no_display`	bool	not set (auto)	`true` disables X11/Wayland
`no_worktree`	bool	not set (auto)	`true` disables linked Git worktree metadata passthrough
`no_mise`	bool	not set (auto)	`true` disables mise integration
`ssh`	bool	not set (off)	`true` shares `~/.ssh` read-only + forwards `SSH_AUTH_SOCK`
`pictures`	bool	not set (off)	`true` shares `~/Pictures` read-only
`browser_profile`	string	not set (auto)	Browser isolation profile: `"hard"` for ephemeral state, `"soft"` for persistent ai-jail-only state, or `"off"` to disable browser auto-detection
`no_save_config`	bool	not set (enabled)	`true` disables automatic `.ai-jail` writes
`no_hide_config`	bool	not set (enabled)	`true` keeps the project's `.ai-jail` file visible to the agent. Default is to auto-mask it as an empty file (see security notes).
`claude_dir`	path	not set	Custom Claude Code config directory (sets `CLAUDE_CONFIG_DIR`). Bind-mounted read-write. Use for multiple Claude profiles per project. Leading `~/` expanded against `$HOME`.
`no_landlock`	bool	not set (auto)	`true` disables Landlock LSM (Linux only)
`no_seccomp`	bool	not set (auto)	`true` disables seccomp syscall filter (Linux only)
`no_rlimits`	bool	not set (auto)	`true` disables resource limits
`lockdown`	bool	not set (disabled)	`true` enables strict read-only lockdown mode

Status bar preferences (no_status_bar, status_bar_style, resize_redraw_key) are stored in $HOME/.ai-jail (global user config), not in per-project .ai-jail files. status_bar_style accepts "dark", "light", or "pastel" — pastel rotates through a curated set of soft pastel palettes (with high-contrast foreground), picking a new one at random for each session. Set it back to "dark" or "light" to disable the rotation. resize_redraw_key is used only by the PTY/status-bar path on terminal resize; accepted values are ctrl-l, ctrl-shift-l (same wire encoding as ctrl-l), or disabled. If unset, codex gets the ctrl-shift-l default and other commands stay off.

When a boolean field is not set, the feature is in auto mode. For resource passthroughs, that means enabled if the resource exists on the host. For Git worktrees, that means enabled only when the current directory is a validated linked worktree. no_save_config is exception: when unset, config auto-save is enabled in normal mode.

Windows

ai-jail doesn't support Windows natively and probably never will. The sandbox depends on Linux namespaces (via bwrap) and macOS seatbelt profiles (via sandbox-exec). Windows has nothing equivalent in userspace. AppContainers exist but they're a completely different API, need admin privileges for setup, and the security model doesn't map to what bwrap does. A Windows port would be a separate project, not a backend swap.

If you're on Windows, run ai-jail inside WSL 2. WSL 2 runs a real Linux kernel, so bwrap works normally.

Setup

Install WSL 2 if you haven't:

wsl --install

Open your WSL distro (Ubuntu by default) and install bubblewrap:

sudo apt update && sudo apt install bubblewrap

Build ai-jail from source inside WSL:

cd ~/Projects
git clone https://github.com/nicholasgasior/ai-jail.git
cd ai-jail
cargo build --release
cp target/release/ai-jail ~/.local/bin/

Run it from inside WSL against your project directory:

cd /mnt/c/Users/you/Projects/my-app
ai-jail claude

WSL 2 mounts your Windows drives under /mnt/c/, /mnt/d/, etc. The sandbox sees the Linux filesystem, so all the mount isolation works as expected. Your Windows files are accessible through those mount points.

One thing to watch: WSL 2 filesystem performance is slower on /mnt/c/ (the Windows side) than on the native Linux filesystem (~/). For large projects, cloning into ~/Projects/ inside WSL instead of working from /mnt/c/ makes a noticeable difference.

License

GPL-3.0. See LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 157 Commits
.github/workflows		.github/workflows
dist		dist
docs		docs
releases		releases
src		src
tests		tests
.ai-jail		.ai-jail
.envrc		.envrc
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
rust-toolchain.toml		rust-toolchain.toml
rustfmt.toml		rustfmt.toml

Folders and files

Latest commit

History

Repository files navigation

ai-jail

Install

Homebrew (macOS / Linux)

cargo install

mise

Nix (flake)

GitHub Releases

From source

Dependencies

Ubuntu 24.04+ / Debian 13+ users

Quick Start

Security notes

Defense-in-depth layers (Linux)

What this is and isn't

Lockdown mode

Browser profiles

Desktop launcher

What gets sandboxed

Default behavior (no flags needed)

Home directory handling

Namespace isolation

Landlock LSM (Linux)

Status bar

mise integration

Usage

Commands

Options

Examples

Config file (.ai-jail)

Merge behavior

Available fields

Windows

Setup

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 27

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Config file (`.ai-jail`)

Packages