Appearance

Quick Start ​

Prerequisites ​

  • Linux 6.13 or later
  • jai installed (setuid root or invoked via sudo)

You can start using jai immediately; it creates default configuration files on first use. Still, it is usually a good idea to create them explicitly before your first real sandbox so you can inspect the defaults:

bash
jai --init

This populates $HOME/.jai/ with a .defaults file containing sensible blacklists for sensitive dotfiles (.ssh, .gnupg, etc.) and environment variables (tokens, keys, passwords). You may want to look at and edit $HOME/.jai/.defaults. If your home directory is on a network file system, uncomment the storage line in $HOME/.jai/.defaults and point it to a directory you can write on a local file system.

Launch a jailed shell ​

With no arguments, jai drops you into a sandboxed shell:

bash
cd ~/my-vibecoded-project
jai

Inside the jail:

  • Software has full read/write access to the current working directory in which you ran jai.
  • Your home directory is a copy-on-write overlay — changes are stored in $HOME/.jai/default.changes and do not affect your real home.
  • /tmp and /var/tmp are private. (Outside the jail you can access the private /tmp directory as /run/jai/$USER/tmp/default.)
  • Everything else on the file system is read-only (though devices remain read-write).
  • Processes inside the jail have a private PID namespace and cannot kill or ptrace processes outside the jail

Type exit to leave the jail.

Note: if you run jai in your home directory it will refuse to grant all of your files to the sandbox. You can run jai -D to avoid granting the current working directory.

Run a command ​

bash
jai codex

This runs codex inside the default casual sandbox. If no command is given, jai starts a shell; if a command is given, jai directly runs the command.

Grant extra directories ​

To grant jailed process write access to additional directories:

bash
jai -d /local/build your-tool

You can pass -d multiple times. You must own the directories you grant.

Suppress automatic cwd access ​

By default, jai grants access to your current working directory. To suppress this:

bash
jai -D -j claude bash

With -D and no -d flags, your entire home is either copy-on-write (casual) or empty (strict/bare), and nothing is directly exported.

Named jails ​

Named jails give each tool its own isolated home directory:

bash
jai -j claude claude

This creates (or reuses) a jail named claude. Named jails default to strict mode when they are created — meaning the jailed program runs as the unprivileged jai user with an empty home directory. Granted directories are exposed via id-mapped mounts.

If the jai system user does not exist or if your home directory is on NFS, jai will be unable to run in strict mode, and you will need to specify bare mode with -mbare.

You can also use casual mode with named jails, as in:

bash
jai -j claude -mcasual claude

The default mode for a jail is set in the corresponding .jai file, e.g., $HOME/.jai/claude.jail.

If you want a newly created strict or bare jail to start with dotfiles or tool-specific state, add an initjail directive to the relevant config file. See Configuration for details and Recipes for an example.

Tear down ​

To unmount all overlays and clean up temporary state:

bash
jai -u

This destroys private /tmp directories and removes overlay work files. Run this when you want a fresh start or before making any modifications to overlay change directories.

To tear down just one named jail instead of all of them, run:

bash
jai -u -j claude

Next steps ​

  • Modes — understand casual, strict, and bare mode
  • Configuration — config files and per-command settings
  • Recipes — practical examples for Claude Code, Codex, and more