Appearance

Configuration ​

jai uses line-based configuration files that live in $HOME/.jai/ (or $JAI_CONFIG_DIR if set).

Config file lookup ​

When you run jai cmd, jai looks for a configuration file in this order:

  1. $HOME/.jai/cmd.conf — if cmd contains no slashes and does not start with .
  2. $HOME/.jai/default.conf — fallback

You can override this with -C file or --conf file. If the path contains no /, it is relative to $HOME/.jai/.

Syntax ​

Each line has the form:

option [value]

option is any long command-line option without the leading --. For example:

conf .defaults
mode casual
dir /local/build
mask Mail

If you need to set an option to the empty string, use =:

storage=

Blank lines and comments are ignored.

The conf directive ​

conf acts as an include directive. It logically replaces the conf line with the contents of the specified file at that exact point. Relative paths are relative to $HOME/.jai/.

conf .defaults
mode strict
dir /extra/path

This reads .defaults first, then the subsequent lines override anything set in .defaults. Because conf is processed inline (not at the end), the order matters: later lines override earlier ones.

The .defaults file ​

jai auto-generates a .defaults file with sensible defaults — blacklists for sensitive dotfiles (.ssh, .gnupg, etc.) and environment variables (tokens, keys, passwords). You should begin most configuration files with:

conf .defaults

You can see the default contents with:

bash
jai --print-defaults

The command directive ​

jai executes jailed programs through bash. The command directive lets you wrap or modify command execution. The default is:

command "$0" "$@"

Where $0 is the command and $@ is its arguments. You can use this to set environment variables, activate virtual environments, or add flags.

Example: Python virtualenv ​

Create $HOME/.jai/python.conf:

conf default.conf
mode strict
dir venv
name python
command source $HOME/venv/bin/activate; "$0" "$@"

Running jai python will now activate the virtualenv before executing the command.

Example: PATH for Claude Code ​

Create $HOME/.jai/claude.conf:

conf .defaults
name claude
mode strict
command PATH=$HOME/.local/bin:$PATH "$0" "$@"

CLI precedence ​

Command-line options are parsed both before and after the configuration file. This means command-line arguments always take precedence over config file directives.

Within a configuration file, the conf directive reads the included file at the exact point of the directive — it overrides previous lines and is subject to being overridden by subsequent lines.

Example: full config file ​

conf .defaults
mode strict
name claude
dir .local
mask .bash_history
command PATH=$HOME/.local/bin:$PATH "$0" "$@"

This:

  1. Loads sensible defaults (blacklists, etc.)
  2. Enables strict mode
  3. Names the jail claude
  4. Grants access to ~/.local inside the jail
  5. Hides .bash_history
  6. Prepends ~/.local/bin to PATH before running the command

Stanford SCS