Architecture Decision Records
ADR 0025: The Server Does Not Manage Its Own External Address
On this page
Status: Accepted Date: 2026-09-27
Context
The server's external address—the address used to access the console in a browser, the address targeted by --server in agent installation commands, and the address in inference gateway integration examples—previously had several conflicting sources: "Access endpoints" on the settings page (the persisted access setting), server.yaml's public_url / --public-url, inference from request Host / X-Forwarded-Host (ADR 0012), and a fallback to the local outbound interface when inference fails. With these four sources combined, behavior is hard to predict depending on whether the reverse proxy rewrites Host, whether TrustedProxies is configured, and whether access overrides public_url. An incident has already occurred where a reverse-proxy setup inferred an internal address that nodes could never reach (see the original ADR 0012).
The fundamental problem is that the server has no reliable way to know "how others connect to me." Different people may simultaneously access the same server through a domain name, a reverse proxy, NAT port forwarding, or direct LAN access. These addresses differ, so any single address stored or guessed by the server is inevitably wrong for some access paths.
There is a similar issue on the serving-network side: serving_source requires you to explicitly declare the local source address used by the gateway to connect to a node's serving network, although the routing table can already make that decision. Another configuration item is simply another opportunity for misconfiguration.
Decision
- The server no longer stores or infers its own external address: remove the "Access endpoints" settings card and the
accesssetting (GET/PUT /api/v1/settings/access), theserver.yamlkeypublic_urland--public-url/GPUWORKS_PUBLIC_URL, address inference from requestHost/X-Forwarded-Host(resolvePublicURLand related logic), the fallback to the local outbound interface when inference fails, and the explicitserving_sourcesource-address setting for serving-network connections. - The party that has the address supplies it; the server does not calculate it:
- Wherever the UI provides the server address (adding nodes, cloud-provider installation, integration examples on the API Key page, and "View Code" in Playground), prefill it with the browser's current
window.location.origin. You can change it to a domain name or reverse-proxy address; - On the API side (node creation, SSH onboarding, and cloud-provider installation), accept this address as the required
server_urlfield, with no implicit source. Return 400 if it is missing or is not an absolute http(s) address without credentials, a query, or a fragment; do not silently fall back; /install.shcontains no built-in address and accepts only the explicit--serverargument in the installation command;- Requests initiated by the server itself ("Initiate from Server" in evaluation) use the loopback address
http://127.0.0.1:<console-port>, because the server is connecting to itself and there is no question of how others connect to it. Return 503 if no console port is bound; - Serving-network connections no longer bind a source address; the local routing table selects the outbound interface based on the destination.
- Wherever the UI provides the server address (adding nodes, cloud-provider installation, integration examples on the API Key page, and "View Code" in Playground), prefill it with the browser's current
- Retain "Listen addresses," but give it only this meaning: the local
IP:portendpoints bound by the server (plus the always-present127.0.0.1). Which address others use to connect—domain name, reverse proxy, or NAT forwarding—is entirely their choice, independent of and unaffected by the listen-address value.
Consequences
- API callers (the UI, scripts, and third-party integrations) must now know and supply the correct
server_url. There is no longer a fallback that "works without configuration." In return, the address always matches the one the caller actually intends to use, without being overridden or misidentified by server guesses. - Installed agents recognize only the address baked into the installation command. Changing the node-access listen address, reverse proxy, or domain does not automatically update installed nodes; you must maintain the corresponding forwarding or reinstall them.
- If an old
server.yamlstill containspublic_url/serving_source, startup rejects it as containing unknown configuration keys. Remove them manually before restarting. - The three-level resolution described in ADR 0012 (explicit configuration > request Host inference > local outbound IP fallback) is no longer current behavior. It is marked as superseded by this ADR, with the original text retained for traceability.
Alternatives Considered
- Keep three-level resolution and simply merge "Access endpoints" with
public_url: this does not solve the underlying problem. With reverse-proxy rewriting, SSH port forwarding, container NAT, and similar setups, the request Host may still be neither "the address the browser sees" nor "the address the agent should connect to." Merging removes one configuration location but leaves the failure modes unchanged. - Have the server probe several candidate addresses and choose the best: no reliable signal identifies which candidate is reachable for the person making the request. If an unreachable address is selected, failure surfaces only after node installation, making diagnosis harder than the current requirement to provide an explicit address.
- Remove only the "Access endpoints" settings card and retain file-based
public_urlas a fallback: in reverse-proxy setups, this value is almost always the internal address at configuration time. Changing subnets or migrating requires remembering to edit it manually. This makes the same class of mistake as the local outbound-interface fallback, just through a different configuration entry point.
Related
- ADR 0012 (superseded by this ADR): the original decision and subsequent updates for three-level PublicURL resolution
- ADR 0030: node network objects and the definition of the serving-network role
- Configure Node Networks: operating instructions for listen addresses and "how others connect"
artifacts/archive/2026-09-27-server-address-cleanup/plan.md: the plan and acceptance records for this change
Was this page helpful?