Installation¶

Jailrun brings FreeBSD to your machine and manages isolated jails inside it — each with its own filesystem, network, and processes. Define your stack in a single config file and bring it up with one command.

Prerequisites

Jailrun runs on macOS (Apple Silicon and Intel), Linux (x86_64 and aarch64), and FreeBSD (x86_64 and aarch64). On macOS, Homebrew handles all dependencies automatically. On Linux and FreeBSD, install the system dependencies first.

Jailrun uses QEMU to run a FreeBSD virtual machine on your host. QEMU provides hardware-accelerated virtualisation via HVF on macOS, KVM on Linux, and TCG emulation on FreeBSD.

macOS Linux FreeBSD

Install via Homebrew:

brew tap hyphatech/jailrun
brew install jailrun

This installs jrun and all its dependencies — Python, QEMU, Ansible, and mkisofs.

Install system dependencies:

# Debian/Ubuntu
sudo apt install qemu-system mkisofs ansible

# Fedora
sudo dnf install qemu-system-x86 genisoimage ansible

# Arch
sudo pacman -S qemu-full cdrtools ansible

Install Python 3.13+ using your operating system's package manager or preferred installation method.

Install uv using your distribution's package manager if available, or via the official installer:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install jrun:

uv tool install jailrun

Install system dependencies:

sudo pkg install qemu edk2-qemu-x64 uv rust cdrtools python313

Some Python dependencies may not have prebuilt wheels on FreeBSD and may need to be compiled locally, so rust is required.

Install Ansible and jrun with Python 3.13:

uv tool install --python 3.13 --with-executables-from ansible-core ansible
uv tool install --python 3.13 jailrun

Tip

If jrun is not found after installation, make sure uv's user bin directory is on your PATH:

export PATH="$HOME/.local/bin:$PATH"

Tip

To install jrun directly from the latest source:

uv tool install "git+https://github.com/hyphatech/jailrun.git@main"