Appearance

Install / Build ​

jai is Linux-only and runs on kernel version 6.13 or later.

Package install ​

Arch Linux ​

jai is available as an AUR package for Arch Linux. If you use an AUR helper such as yay, you should be able to install it directly:

bash
yay -S jai

Otherwise, like all AUR packages for Arch Linux, you can install it manually as follows:

bash
curl -L https://aur.archlinux.org/cgit/aur.git/snapshot/jai.tar.gz | tar xzf -
cd jai
makepkg -i

Debian ​

While the best supported way to install jai is from a release jai-x.y.tar.gz file, the github releases page also contains a .deb file with a binary. If you download this file, you can install jai on an amd64/x86_64 host with:

bash
apt install ./jai-x.y-1_amd64.deb

The .deb file is less well tested than a source install, so please report any problems with it on the GitHub issues page.

Keep in mind that you will need to upgrade to a 6.13 or later kernel to use the overlay file system in casual mode. You can allegedly obtain a modern linux kernel on Debian trixie through Debian backports as follows, though the author has not tested it:

bash
cat > /etc/apt/sources.list.d/debian-backports.sources <<'EOF'
Types: deb deb-src
URIs: http://deb.debian.org/debian
Suites: trixie-backports
Components: main
Enabled: yes
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
EOF

sudo apt update
sudo apt install -t trixie-backports linux-image-amd64 linux-headers-amd64
sudo reboot

Ubuntu ​

The instructions for Ubuntu are similar to Debian, except that it is easier to run a modern kernel on Ubuntu. Ubuntu 25.10 already ships with a new enough kernel for jai, and 24.04 makes modern kernels available through the Hardware Enablement (HWE) stack, which most desktops follow. You can enable HWE as follows:

bash
sudo apt update
sudo apt install --install-recommends linux-generic-hwe-24.04
sudo reboot

Build/install from source ​

Dependencies ​

jai requires a C++23 compiler (verified on GCC 14, GCC 15, Clang 19, and Clang 22). Debian bookworm only goes up to GCC version 12, but has Clang 19. On such a system you will need to install both clang-19 and libc++-19-dev, because GCC 12's libstdc++ is too old. Set the environment variable CXX="clang++-19 -stdlib=libc++" to get clang and LLVM's libc++.

If you are building from git instead of a release, you also need:

  • Standard autotools (autoconf, automake) for the build system
  • pandoc to format the man page

Most modern linux systems with a development environment installed should satisfy all of the above dependencies except pandoc, which is slightly less standard but still widely available.

Build ​

You can install jai from a stable release (recommended), or from git.

jai requires a dedicated untrusted user for strict sandboxes, called jai by default. The jai user must be different from nobody (which is the "overflow" user in id-mapped mounts), and the account name will be embedded into the jai binary. If your system already has a user named jai, then jai will pick the name _jai. You can override this choice in the instructions below by changing the ./configure to specify an alternate name, for instance unprivileged:

./configure --with-untrusted-user=unprivileged

Building a release ​

Download the latest release from GitHub. Make sure to download the file called jai-version.tar.gz. (The assets labeled "Source code" are generated by GitHub from the git tag; they are missing some generated files like the man page and configure script and so require additional tooling to build.)

Unpack, configure, and build the release as follows:

bash
tar xzf jai-x.y.tar.gz
cd jai-x.y
./configure
make

Building from git ​

To build the latest version from git, run the following commands:

bash
git clone https://github.com/stanford-scs/jai.git
cd jai
./autogen.sh
./configure
make

Installation ​

Run the following two commands to install jai and create the unprivileged jai user (if it does not already exist on your system):

bash
sudo make install
sudo systemd-sysusers

systemd-sysusers creates the unprivileged jai user account, but will only find the configuration file if you installed with a prefix of /usr/local (the default) or /usr. If you install jai elsewhere, you need to supply the jai.conf file as a command-line argument. For example, in the build directory:

bash
sudo systemd-sysusers ./jai.conf

You can also just create an account named jai, but note that jai is very picky about the account. In the password file, the Gecos field must be exactly JAI sandbox untrusted user and the home directory must be /. Otherwise, jai is paranoid that you might have a real user named jai on your system. Here is a command to create the user manually:

bash
useradd -rMU -s /usr/bin/nologin -d / -c 'JAI sandbox untrusted user' jai

Note that jai must run as root (it uses unshare and various privileged file system and mount-related syscalls), so it gets installed setuid root. If you do not want to install it setuid root, you can install it manually and run it with sudo.

You can start using jai immediately; it will create the default configuration files on first use. However, it is usually worth initializing them explicitly first so you can inspect or edit the defaults before you run an agent:

bash
jai --init

This creates default configuration files in $HOME/.jai/, including the .defaults file that ships sensible blacklists for sensitive dotfiles and environment variables.

Alternate configuration file locations ​

If your home directory is on NFS, you may want to relocate jai's configuration and storage:

bash
export JAI_CONFIG_DIR=/local/disk/.jai
jai --init

This puts all configuration files, private home directories, and overlay storage on a local filesystem where extended attributes and overlayfs work correctly.

If you wish to keep configuration files in your home directory but move storage to local disk, then instead of setting JAI_CONFIG_DIR you can put a line storage /local/disk/jai-storage in $HOME/.jai/.defaults to move just the private home directory storage to local disk.