Appearance

Quick Start ​

Prerequisites ​

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

First-run setup ​

Before using jai for the first time, create default configuration files:

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).

Launch a jailed shell ​

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

bash
jai

Inside the jail:

  • Your current working directory has full read/write access
  • 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
  • Everything else on the filesystem is read-only
  • Processes inside the jail cannot kill or ptrace processes outside (private PID namespace)

Type exit to leave the jail.

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 runs it directly.

Grant extra directories ​

To give the 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 -n 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 -n claude claude

This creates (or reuses) a jail named claude. Named jails default to strict mode — the process runs as the unprivileged jai user with an empty home directory, and only granted directories are exposed via id-mapped mounts.

If the jai system user does not exist, named jails fall back to bare mode.

Tear down ​

To unmount all jail 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 editing overlay change directories.

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

Stanford SCS