Guides

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.

On this page