Introduction

What nibrunner is and how these docs are organized.

nibrunner runs apps in Firecracker microVMs on one Linux machine. It is a single binary, nibrunnerd. You list the apps you want in a JSON file. The daemon boots each one in its own microVM and keeps it running. Each microVM runs through Firecracker's jailer with its own filesystem boundary and non-root host identity. An app is not a container image. It is a binary, or a filesystem image, stacked as a layer on the Debian image the host ships.

Features

  • Sleep and wake. An app with no traffic is snapshotted and suspended. The next request wakes it. A machine that runs a few dozen apps at once can hold hundreds.
  • Backups and snapshots. Volumes can live in an object store, so they survive the machine. A checkpoint is a point-in-time copy of a volume. An export is an archive of a volume that a new volume can start from.
  • HTTPS. A built-in proxy routes each hostname to its app. It terminates TLS itself or sits behind an edge that does. Non-HTTP ports (ssh, DNS, WireGuard) are forwarded as-is and also wake a sleeping app.
  • Custom images. An app's root filesystem is a stack of layers on top of the Debian image nibrunner ships. A layer is one executable, or a squashfs or ext4 image you built. A volume can be seeded from an archive.
  • Logs and metrics. Each app's output goes to its own log file. The host serves a Prometheus endpoint.

How these docs are organized

  • Getting started: install a host, deploy an app, configure the host. Read in order.
  • Guides: one feature per page.
  • Reference: every key of config.toml, desired.json and reported.json, generated from their JSON Schemas. It is a separate tab next to Docs.

Search with Ctrl+K or Cmd+K.

Requirements

  • Linux x86_64 with /dev/kvm. Bare metal, or a VPS whose provider enables nested virtualisation.
  • Debian or Ubuntu with systemd.
  • Root, and outbound HTTPS.

On this page