Architecture Decision Records
ADR 0045: The Exposure Connector Runs in a Separate Connector Service, Independent of Server Starts and Stops
On this page
Date: 2026-10-14 · Status: Accepted; changes the tradeoff in the Exposure Plan that “the server manages the connector, and both share the same lifetime”
Context
Previously, gpuworks expose had the server manage cloudflared: a helper watched a pipe held by the server, and any server exit (including SIGKILL) also terminated the connector. The systemd control-group likewise killed it when the server restarted. The rationale at the time was that “an exposure pointing at a stopped server is worse than having to recreate the exposure.”
In practice, this cost is too high: quick tunnel addresses are assigned per connector, so every server restart or upgrade produces a new address and invalidates links already shared. When the server is stopped, however, the old address only returns a Cloudflare error page; it does not send traffic to someone else.
Decision
- A separate connector service:
gpuworks expose runruns the original supervisor (cloudflared download, network retries, probes, status), which manages cloudflared. The helper's liveness pipe is rebound to this service, so the connector exits when the service exits (including when killed by SIGKILL). The server no longer manages exposure; it only writes its actual listen address to<data>/expose/server-origineach time it starts. - Manual startup by default:
expose upstarts the service as a background process (in a separate session, outside thegpuworks.servicecgroup), with no automatic recovery after a machine reboot.expose up --systemdinstalls a separategpuworks-expose.service(Restart=on-failure, enabled at boot).gpuworks.serviceitself is not modified. - Write the forwarding target into configuration:
updetermines the origin in the order--origin> the server-recorded address >server.yamlin the installation directory, and writes it toconfig.json. An origin change counts as a new request. - An absent server is not a failure: if the local origin probe cannot reach the server, mark exposure as
degradedand keep the connector. Restorereadywhen the server returns. - The service exits when exposure is disabled: after exposure is disabled, the service stops the connector and exits with code 0 (hence
Restart=on-failurein the unit).expose downwaits for the service to exit; with--systemd, it also runsdisable --nowand removes the unit. - Runtime account: the service runs as the owner of the data directory. When root executes
up, it drops privileges to that account; the systemd unit specifiesUser=.
Tradeoffs
- The address still resolves while the server is stopped, but returns an error page. In exchange, the address stays the same after server restarts and upgrades.
- The default background process does not recover after a machine reboot, so you must run
upagain manually. Explicitly choose--systemdfor automatic startup. This avoids changing the server unit or adding a boot service that the user did not request. - Each data directory can have only one connector service (using the existing supervisor lock). Restarting the connector service itself recreates the connector and changes the quick address.
Was this page helpful?