URLs and domains

Every machine and every service has a permanent address, minted from its name the moment it is created. Permanent means what it says: the same address survives suspend, wake, checkpoint, restore, redeploy, rollback, promotion and a move to another host.

The shape of an address

https://scratch.pilotrun.app          a machine, port 8080
https://web.pilotrun.app              a service
https://3000-scratch.pilotrun.app     another port in the same machine

The router dials port 8080 inside the guest, which is what every framework recipe sets up. A port prefix on the hostname reaches another port over HTTP, and a tunnel reaches anything that is not HTTP at all.

A request that arrives while the machine is asleep is HELD while it wakes, for up to 120s, rather than answered with a waiting page. That is one number for a machine on the host you reached and for a machine one host over, so nothing a client can measure tells it where its sandbox lives.

Who may reach it

pilot url scratch
pilot url update --auth org scratch

Use public for anything meant to be shared or to take webhooks. Use org for a sandbox an agent is working in: it starts listening the moment it comes up, and org keeps that between you and the fleet. A promoted machine follows its service's mode.

No address at all

A service with nothing to serve on the web, a worker or a database, asks for none with private: true. Peers in the same app still reach it at <name>.internal, and nothing outside can.

A service that was created private can be given an address later, exactly once, with pilot service set --domain. An address is permanent, so a service that already has one is refused rather than renamed.

A hostname you own

pilot domain add shop.example.com web
pilot domain ls

1. pilot domain add records the hostname and answers with the record to create at your registrar.
2. You create the record. DNS takes minutes, and there is nothing to poll.
3. pilot domain ls shows the name as verified once it resolves, and a certificate is issued for it.
4. The service then serves on both its own address and yours. The original keeps working.

• Verification comes before the certificate, because an unverified name would spend the fleet's shared certificate rate limit on a name nobody owns.
• A name under the fleet's own apex is refused. That name is already minted for somebody, and accepting it would let one tenant claim another's address.
• Adding a domain is a command you run rather than a call an agent makes, because it needs a DNS record only you can create.

The addresses your traffic leaves from

pilot egress lists them. There is one per host, because each host derives its own from its routed prefix, and an allowlist at the other end has to carry the WHOLE set: a machine can be created on, moved to, or rescued onto any host in the fleet.

The set changes only when a host joins or leaves the fleet. It does not change when your machines are created, destroyed, resized, rolled or moved, which is why the answer is per organization rather than per machine.