Getting started

Deploy an app

Upload a binary, write desired.json, and reach the app by hostname.

An app is an entry in desired.json with one or more layers. The host stacks the layers on its Debian image and runs config.command in a microVM as uid 65534.

This page deploys one binary. A static Linux x86_64 binary (Go, Rust, Zig, a compiled Bun executable) needs nothing else. A dynamically linked one gets glibc, libstdc++ and CA certificates from Debian's slim image. An app that needs a runtime (PHP, Python, Node), or that comes from a Dockerfile, can use an OCI image.

Upload the binary

Copy it into the artifact store under a key of your choice, and record its SHA-256. On a host set up by the installer, the artifact store is a directory:

install -D -m 0644 ./my-server /var/lib/nibrunner/artifact-store/my-server
sha256sum ./my-server

Write desired.json

nibrunnerd watches /var/lib/nibrunner/desired.json and applies every change to it. Fill in the key and the digest from the previous step:

/var/lib/nibrunner/desired.json
{
  "hostId": "host-1",
  "revision": "deploy-1",
  "volumes": [
    { "volumeId": "vol-1", "appId": "app-1", "sizeBytes": 8589934592, "desiredState": "present" }
  ],
  "instances": [
    {
      "appId": "app-1",
      "deploymentId": "dep-1",
      "volumeId": "vol-1",
      "desiredState": "on-request",
      "layers": [
        {
          "kind": "executable",
          "destinationPath": "/app/server",
          "digest": "<sha256 of the binary, lowercase hex>",
          "objectKey": "my-server"
        }
      ],
      "config": {
        "httpPort": 3000,
        "command": { "program": "/app/server", "args": [], "workingDirectory": "/app", "environment": {} },
        "resources": { "vcpuCount": 1, "memoryMib": 256 },
        "healthCheck": { "kind": "http", "path": "/healthz", "intervalMs": 5000, "timeoutMs": 2000, "gracePeriodMs": 30000, "healthyThreshold": 1, "unhealthyThreshold": 3 },
        "restartPolicy": { "maxRestarts": 5, "initialBackoffMs": 500, "maxBackoffMs": 30000, "backoffFactor": 2, "resetAfterMs": 60000 }
      },
      "hostnames": [{ "hostname": "app-1.example.com", "kind": "platform" }],
      "access": { "kind": "public" }
    }
  ],
  "checkpoints": [],
  "exports": []
}
FieldMeaning
revisionYour own name for this version of the file — a deploy id, a commit, a counter. The host never reads it; it hands it back in reported.json as acceptedRevision so you can tell which version it is on.
volumesOne volume per app. It is formatted empty the first time it appears in the file. All of the app's writes go to it, and it is the only thing that gets backed up.
layersWhat the root filesystem is built from. An executable layer is one program, packed into an image at destinationPath.
config.commandThe program to run, as uid 65534.
config.healthCheckHow the host decides the app is up. Required; there is no default.
desiredStateon-request starts the app now and lets it sleep when idle. running keeps it up. stopped stops it.
hostnamesHostnames the proxy routes to httpPort.

The reference lists every field.

Changing revision on its own changes nothing

revision is yours to name and the host never interprets it: it is not a version number, it is not compared with the one before it, and a file that changed only its revision starts, stops and replaces nothing. It is there so that acceptedRevision in reported.json answers which of your versions is this host on in the words you already use, rather than as a digest you have to work out.

Reach it

The daemon formats the volume, packs the binary into an image, boots the microVM, and reports the instance running once GET /healthz on port 3000 returns 2xx.

The proxy routes on the Host header, so you can test before DNS exists:

curl -H 'Host: app-1.example.com' http://127.0.0.1/

Point app-1.example.com at the machine and the same request works from anywhere.

Where to look when something is wrong

  • /var/lib/nibrunner/reported.json: the state of every volume, instance, checkpoint and export in desired.json, with a reason when something failed. An instance that cannot start is explained here, not in a log. Its acceptedDigest is the sha256sum of the desired.json the daemon took up, so sha256sum /var/lib/nibrunner/desired.json tells you whether your last edit landed; message says why if it did not. The file is rewritten when something changes, and every 15 seconds whether or not anything did, so reportedAt shows the daemon is alive.
  • /var/lib/nibrunner/logs/<appId>.jsonl: the app's stdout, stderr and lifecycle events as JSON lines.
  • journalctl -u nibrunnerd: the daemon's own log.

Editor support

Add "$schema": "https://raw.githubusercontent.com/ilbertt/nibrunner/main/crates/protocol/schema/desired.schema.json" to the file and your editor validates and autocompletes it.

On this page