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-serverWrite 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:
{
"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": []
}| Field | Meaning |
|---|---|
revision | Your 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. |
volumes | One 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. |
layers | What the root filesystem is built from. An executable layer is one program, packed into an image at destinationPath. |
config.command | The program to run, as uid 65534. |
config.healthCheck | How the host decides the app is up. Required; there is no default. |
desiredState | on-request starts the app now and lets it sleep when idle. running keeps it up. stopped stops it. |
hostnames | Hostnames 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 indesired.json, with a reason when something failed. An instance that cannot start is explained here, not in a log. ItsacceptedDigestis thesha256sumof thedesired.jsonthe daemon took up, sosha256sum /var/lib/nibrunner/desired.jsontells you whether your last edit landed;messagesays why if it did not. The file is rewritten when something changes, and every 15 seconds whether or not anything did, soreportedAtshows 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.