Modes

jai has three execution modes. Each trades off convenience, confidentiality, and compatibility differently. All three modes use a private PID namespace, so jailed processes cannot kill or ptrace anything outside the jail.

Casual mode

The default for unnamed jails. Think of casual mode as easy protection against tools corrupting your .bashrc or deleting all your files. Mind you, rm -rf ~ will still wipe out the directory in which you ran jai (but it's a git repository mirrored elsewhere, right?), but it won't wipe out your whole home directory.

jai                # default sandbox is casual by default
jai -mcasual codex # explicit

• Your home directory is mounted as a copy-on-write overlay. The jailed process sees your real files, but writes go to $HOME/.jai/default.changes instead of modifying originals, except in the directory where you ran jai.
• Your current working directory grants full read/write access to code in the jail (unless suppressed with -D). So files deleted there are really gone.
• /tmp and /var/tmp are private.
• The rest of the filesystem is read-only.

Casual mode does not protect confidentiality. The jailed process runs as your user and can read most of your files. It is designed to prevent easy filesystem damage, not to hide secrets.

You can hide specific files with the --mask option or by deleting them from the overlay home at /run/jai/$USER/*.home.

Strict mode

The default for named jails. Think of strict mode as "a real confidentiality step-up."

jai -j claude claude          # strict by default (named jail)
jai -mstrict codex            # explicit

• The process runs as the unprivileged jai system user, not as you.
• Home directory is an empty private directory at $HOME/.jai/<name>.home.
• Granted directories (via -d or cwd) are exposed with id-mapped mounts — files look like they are owned by jai inside the jail.
• Because the process has a different UID, it cannot read files outside your home directory that are only accessible to your user — this is where confidentiality comes from.

Strict mode requires the jai system user to exist. It does not work with NFS filesystems, because NFS does not support id-mapped mounts.

Bare mode

A compatibility fallback. Bare mode exists for systems where strict mode is not available — primarily NFS-backed home directories.

jai -mbare codex

• Home directory is an empty private directory, like strict mode.
• But the process runs as your user, not as jai.
• This means it cannot provide confidentiality — the process can still read any file accessible to your UID outside the home directory.

Use bare mode when you need strict-like home isolation but your filesystem does not support id-mapped mounts.

Default mode selection

The default mode for newly created sandboxes is strict, though you can override this in $HOME/.jai/.defaults. Once a sandbox name is created, the default mode for the sandbox is stored in $HOME/.jai/name.jail. When first initializing your account, jai creates a file $HOME/.jai/default.jail that sets the default mode for unnamed sandboxes to casual, but you can change this by running jai --init and editing the files in $HOME/.jai before using any sandboxes.

Comparison

	Casual	Strict	Bare
Home directory	Copy-on-write overlay of your real home	Empty private home	Empty private home
Process UID	Invoking user	Unprivileged jai user	Invoking user
Confidentiality	Weak — jailed code reads your files	Strong — separate UID blocks access	Weak outside $HOME — same UID as you
Integrity	Overlay captures writes; originals safe	Full isolation; empty home	Full isolation; empty home
NFS support	Yes (make $JAI_CONFIG_DIR local)	No (id-mapped mounts unsupported)	Yes
PID namespace	Private	Private	Private
Best use case	Quick sandboxing, casual coding help	Multi-tool isolation, API key separation	NFS home directories

Which mode should I use?

• Casual if you are just starting out and want something better than nothing. The boundary is so light-weight that everything should just work.
• Strict is what you should really use, because it provides a meaningful level of protection and is still super easy to use. But you will probably want to set up some configuration files in $HOME/.jai to have different configurations and sandboxes for different tools. After the setup, strict mode is basically as easy to use as casual mode.
• Bare if you need strict-like home isolation but your home directory is on NFS.

If none of these is sufficient, maybe you need a proper container or VM. See the Security Model for more information or the author's VM Setup instructions to do something much more secure.