File listings
A local socket that lists directories inside a running app.
The host lists directories inside a guest over a unix socket. It is off unless config.toml
names one:
[filesystem]
socket = "/run/nibrunner/filesystem.sock"Run nibrunnerd start after the edit.
Asking
curl --unix-socket /run/nibrunner/filesystem.sock \
'http://localhost/apps/app-7/files?path=%2Fdata'path is percent-encoded.
{
"path": "/data",
"entries": [
{ "name": "uploads", "kind": "directory", "sizeBytes": 4096, "modifiedAt": "2026-09-22T09:14:02.000Z" },
{ "name": "app.db", "kind": "file", "sizeBytes": 2179072, "modifiedAt": "2026-09-22T11:02:41.317Z" }
],
"truncated": false
}kind is file, directory or other. An answer carries at most 1000 entries; past that it is
cut and truncated is true.
Listings are all it serves. It does not read file contents, and it takes no input: what the host
runs stays desired.json's to say.
Sleeping apps
Asking about a sleeping app wakes it, as an HTTP request would, and the listing is answered once it is up. The request counts as activity, so the idle timer restarts from the moment you ask.
Every click in a file browser wakes the app it points at. Browsing a host where most apps are asleep boots them.
Refusals
Every refusal carries the sentence saying which:
{ "message": "this host has no room to wake app-7: it is 512 MiB short" }The reference lists every status and what each means. It is written from the code, so it cannot fall behind what the socket answers.
Access
The daemon creates the socket on the way up, mode 0600, owned by the account it runs as — root
on a host the installer set up. Anything asking must run as that account, and anything that can
read the socket can list any app's files.