0012 Run as a server, experimental
A nocturne-server program and container image that serve the real app to a browser, signed in with a token kept in the data folder, behind the person's own TLS proxy.
Context
Some people want Nocturne on a home server or another machine that is always on and to use it from a browser.
The development preview (nocturne-preview) already serves the real app over HTTP, but it is
built for one developer session: a token made at every launch, loopback only, a debug build. A
server has to survive restarts, run in a container and be reached through a proxy, without
weakening what the preview guarantees.
Decision
- A program of its own, labelled experimental.
nocturne-server, behind theservercargo feature, which builds on the preview's HTTP front (src-tauri/src/preview/). It ships only as a container image (Containerfile), never in a desktop package; the package check fails if the program or its interface is in one. The documentation calls it experimental until the blockers below are closed. - How it is reached. It listens on
NOCTURNE_BIND(default127.0.0.1:55066). The image listens on0.0.0.0:55066inside its own network, and the guide publishes that port on the host's loopback only. Plain HTTP is for this computer. Anything else goes through a TLS proxy the person runs (Caddy, Tailscale serve, or similar), named inNOCTURNE_PUBLIC_ORIGIN, which must behttps://or a loopbackhttp://address; the server refuses to start otherwise. There is no built-in TLS. TheHostandOriginchecks are the preview's: only127.0.0.1on the port and the public origin are accepted, so a page on another site or a name pointed here cannot use it. - Signing in. A 256-bit token is kept in
server-tokenin the data folder, owner-only. It is made at the first start and never written to the log.nocturne-server tokenprints the sign-in link, andnocturne-server token --rotatereplaces the token; the running server reads the file at every check, so the old link stops working at the next request without a restart. Event and media tickets are tied to the token they were made under and end with it, an open event stream closes within a second or so, and a media ticket lives twelve hours at most however often it is used. A missing or malformed file admits nobody. The link carries the token in the fragment, which never reaches the server in a URL; the page sends it as a bearer header and keeps it in this browser's local storage (the preview keeps its own per tab). There are no accounts: one server is one person. - Health.
GET /healthzneeds no token but needs an accepted host, carries no data, and answers 200 while the store is open.nocturne-server healthcalls it for the image's health check. - What stays the same. The private engine binds loopback inside the container with its
per-launch key. The data folder is a volume (
/data), marked so that the desktop app's folder is never taken over. Models download at first setup with consent, as on the desktop. Event and media tickets, path hiding, upload limits, the converter limits and the interface's content policy are the preview's. The Online answers key is kept in the data folder's owner-only key file. - What does not apply. The tray, keep-awake, start at login, desktop notifications, the system keychain, the global shortcut and quick capture, file and folder dialogs, opening files in the system's apps, printing, exporting to a folder, watching an inbox folder, and Away from home. The page reports these as unavailable. Updating is pulling a newer image; there is no updater inside.
Development shortcuts, and what changes
| Shortcut in the preview | For the server |
|---|---|
| A token made at every launch | Replaced by the token file and its two commands |
| Loopback bind only | Replaced by NOCTURNE_BIND, with https:// required for any other origin |
Built in debug, make preview-real |
The image builds --release: no checkout engine lookup, no NOCTURNE_LOG, no scripted mind, no error details in answers. The engine is found through NOCTURNE_LEMOND |
Tauri's mock runtime and its test call path (tauri::test) run the app without a window |
Kept on purpose: it sends every command through the same window allowlist as the desktop. It is a test API with no stability promise; Cargo.lock pins it and the preview tests cover it. Blocker for leaving experimental |
| Turning on Online answers is printed instead of confirmed in a system window | Kept. The page's own consent screen still runs; a browser has no system window. Whoever holds the token can read everything already, so this adds nothing |
| The app crate links the desktop toolkit | Kept. The image carries those libraries though the server never opens a window, which costs size. Blocker: a headless build of the app crate |
| Logs go to files in the data folder | Kept (/data/logs); the console shows start-up lines only |
ffmpeg found on the path at start |
Kept; the image ships Debian's ffmpeg for browser recordings |
Residual risks
- Between the proxy and the server, traffic is plain HTTP on the host's loopback or the container
network. Publishing the port beyond loopback without a proxy exposes the token on the network the
first time a browser uses it there; the guide never does this, and a plain
http://public origin that is not loopback is refused. - The token sits in the browser's local storage, readable by any script on that origin; the content policy allows scripts from the server only.
- A media file already being sent when the token is replaced finishes sending.
- Anyone who can run commands in the container (
podman exec) can read the token, as on any host. - GPU access inside a container depends on the host's drivers and device permissions; only what the guide names was tried.
Consequences
- No new outbound traffic: the server answers the person's own browsers, and everything else is the desktop app's. Building the image downloads the base images, the interface and Rust dependencies and the pinned engine, as a desktop build does.
make server/buildandmake server/imagebuild it;make checktests the server's token, health and origin rules with the preview's tests.- The image is published by
.github/workflows/container.ymlon release tags; pull requests only build it (building).