A URL Is Part of the Machine's Identity
Suspend, wake, checkpoint, restore, promote, redeploy and host death all leave a Pilots machine's address alone. What it takes to mean that, from one wildcard certificate to who is allowed to fetch a URL at all.
Most platforms mean something narrower by "stable URL" than the reader hears. Usually it means stable until you redeploy, or stable for the app while individual instances come and go behind it.
On Pilots the address is part of the machine's identity, which is a stronger claim and worth stating precisely. A machine's URL survives suspend, wake, checkpoint, restore in place, promotion from sandbox to service, redeployment, and the death of the host it was running on. Any change that can mint a new URL for an existing machine is a bug, and it is written down as one.
The claim is easy to make. What follows is what it costs to mean it.
One apex for every workload, because promote must not move anything
Every workload gets <name>.pilotrun.app. Sandboxes and services share that apex, and they share it precisely because promoting a sandbox must not change its URL. Two apexes would mean a promotion is a migration between them, and a migration between them is a new address, which is the thing we are refusing.
Arbitrary ports get <port>-<name>.pilotrun.app, which is one hostname pattern rather than a port-mapping API.
The dashboard lives on a different apex, pilots.run, and that separation is a security boundary rather than a preference. A guest sharing the dashboard's apex could set cookies scoped to it. User code never shares an apex with the control surface.
A service's label is minted from its name when it is created, and a request to it is routed to whatever machines its current release has. So a blue-green deploy replaces every replica without touching the address: the name resolves to a release, and a release resolves to machines.
One wildcard certificate, N hosts, no coordinator
DNS is a wildcard A record pointing at every host in the fleet. So any host can receive any request, which is the property the no-control-plane design needs.
Certificates are the interesting part, because every host needs the same wildcard certificate and none of them is in charge.
The wildcard is issued through ACME DNS-01 using a Cloudflare API token, and every host calls certmagic.ManageAsync for the same names. The shared certificate storage lock is what turns N identical calls into one order, with the rest loading the result. Not a leader. A lock in shared storage, which is a much smaller thing to get right.
Custom domains are different. They arrive on demand, one at a time, and they use HTTP-01, because any host can answer that challenge. TLS-ALPN is off for exactly that reason: it would have to be answered by whichever host DNS happened to pick, which makes the challenge a coordination problem.
Without a Cloudflare token the router stays HTTP-01 only and the wildcard is simply absent. Custom domains still work. That is a degradation rather than a failure, which is the correct shape for a dependency on somebody else's API.
There is one hostname the control API claims for itself, api.<workload domain>, ahead of the workload suffix check, so that every host answers the documented base URL. That name needs no DNS record and no certificate of its own, because the wildcard already covers it. It also means a tenant may not take that name as a machine name, or they would own a URL nobody could reach them at.
The reservation guards creates, and reports the rest
That reservation has a failure case worth mentioning, because the handling is a small lesson in blast radius.
The name is reserved at create time. But if the API hostname is ever pointed at a name a machine already holds, the machine is reported rather than silently swallowed: hostd logs an error naming it and publishes a metric.
Refusing to start would have been the tidier-looking choice. It would also turn one machine's lost URL into a fleet-wide outage, because the row is replicated to every host and every host would refuse at once. A local problem should not have a global refusal.
Who may reach a URL is a separate question
Permanence is about the address. Access is a different axis, and it is a per-object mode rather than a property of the apex.
url_auth is public, which is the default and what every URL was before the mode existed, or org, where the router demands an API key belonging to the owning org in an Authorization: Bearer header. No key gets a 401 with a WWW-Authenticate: Bearer challenge. Another org's key gets a 403. A promoted machine follows its service's mode.
The part I care about is where the router reads that from. The mode, the tenancy row and the key row all come from the host's own local replica, and on a fleet the mode is materialised into the subscription cache beside the machine and service maps.
That is not an optimisation. A live query in the request path would have a failure mode, and there are only two ways to answer a store error: serve a gated URL to anyone, or refuse a public one. Both are wrong. So the request path holds no query, and therefore has no such failure to handle.
The headers the router owns
Last piece, since it belongs to the same boundary. The router sets the forwarded headers once at the public entry and preserves them across a mesh hop to another host.
X-Forwarded-For is deleted on the way in, so what reaches a guest is the peer this edge actually saw. X-Forwarded-Proto is https when the edge terminated TLS. X-Forwarded-Host is the name the user typed.
And the sibling client-IP headers go with it: X-Real-IP, CF-Connecting-IP, True-Client-IP and RFC 7239's Forwarded. Deleting only one of them moves the forgery rather than ending it, and a rate limiter behind us reads the leftmost entry of whichever header it was written against. A caller must not be able to supply the value that decides whether they are rate limited.
Every note, or install the CLI and try the thing this one is about.