Getting started

Installation

Install nibrunner on a Linux machine and start the host.

Requirements

  • Linux x86_64 with /dev/kvm. Every app runs in a microVM, which needs hardware virtualisation. Bare metal has it. A VPS has it only if the provider enables nested virtualisation. Check with ls -l /dev/kvm. nibrunnerd install refuses to run on a machine without it.
  • Debian or Ubuntu with systemd. The installer uses apt-get. The host runs as systemd units.
  • Root, and outbound HTTPS. The installer downloads the release from GitHub.

Installation and startup require host SMT and KSM to be disabled, with no retained KSM shared pages. Prepare the machine using the host security requirements.

Install

curl -fsSL https://raw.githubusercontent.com/ilbertt/nibrunner/main/deploy/install.sh | sh

The script:

  1. Installs the packages it needs.
  2. Downloads the latest release: the daemon, the guest kernel and the guest image. Each file is verified against its published digest.
  3. Puts nibrunnerd in /usr/local/bin.
  4. Runs nibrunnerd install.

nibrunnerd install sets up the host from /etc/nibrunner/config.toml. If the file does not exist, it writes one: volumes as files on the local disk, plain HTTP on port 80, no object store, and max_apps set to what it measured the machine can hold. It does not start the daemon or ZeroFS. When [host_storage] is configured, it initializes and mounts that storage before creating host directories.

The matching Firecracker jailer is bundled in nibrunnerd. Installation creates the locked nibrunner-jailer system account and reserves the host identities used by each app's VMM. This setup is automatic; there are no jailer settings in config.toml.

Options

  • NIBRUNNER_VERSION=<tag> before the command installs that release instead of the latest.
  • On a machine without apt-get, install nftables, e2fsprogs, kmod, curl and ca-certificates yourself, then run the script again.

Start

nibrunnerd start

start reads config.toml, applies it, and starts the systemd units it names. The file the installer wrote works as-is; you do not need to edit it to deploy a first app. After you edit it, run nibrunnerd start again. It restarts only the units whose configuration changed.

Verify

systemctl status nibrunnerd

To follow the daemon's log:

journalctl -u nibrunnerd -f

Upgrade an existing host

The HTTP listener runs in a separate worker. A daemon restart transfers the listener to its replacement while the old worker finishes responses already forwarded to running guests. Requests waiting for an idle app, or still forwarded through its wake activator, depend on the daemon and can be interrupted by a restart.

After updating nibrunnerd, run nibrunnerd install, then nibrunnerd start. Existing microVMs keep serving until stopped or redeployed. Redeploy apps to move their next boot into a jail. Waking a snapshot from a direct launch cold boots the app while preserving its volume.

On a running ZeroFS host, pending or previously unrecorded service inputs require an explicit restart. Follow the configuration steps before running nibrunnerd start --restart-zerofs; the restart disconnects guest disks.

On this page