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 integrity protection."

jai codex          # 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.
• Your current working directory has full read/write access (unless suppressed with -D).
• /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 -n 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 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

Scenario	Default mode
No -n flag (unnamed jail)	Casual
-n flag and jai user exists	Strict
-n flag but no jai user	Bare (fallback)

You can always override with -m casual, -m strict, or -m bare.

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 — same UID as you
Integrity	Overlay captures writes; originals safe	Full isolation; empty home	Full isolation; empty home
NFS support	Yes	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 want the least friction and mostly care about preventing agents from clobbering files. This is the right default for quick interactive work.
• Strict if you are jailing multiple tools that should not see each other's credentials, or if you want to meaningfully limit what the jailed process can read.
• Bare if you need strict-like home isolation but your home directory is on NFS.

If none of these are sufficient — if you need real multi-tenant isolation or defense against a determined attacker — use a proper container or VM. See the Security Model for more.