All pages
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.
A machine that is awake while nothing in it listens on the port, an app
restarting after a code change or a dev server between two builds, answers
503 with Retry-After: 1 and X-Pilot-Upstream: not-listening.
A browser gets a small page that says the app is starting and reloads itself the moment
the app answers. It carries no name and no logo, because it is shown on your app's
address, and it gives up after a minute with a plain message. Any other client gets a
JSON error whose code is not_listening. A product that shows a machine
inside a frame can read the header to tell "starting" from an error the app returned.
Who may reach it
pilot url scratch
pilot url update --auth org scratch
| Mode | Who gets through |
|---|---|
| public | Anyone with the URL. This is the default. |
| org | Only a request carrying an API key of the owning organization as a bearer token. Anything else is refused, and another organization's key is refused differently. |
| token | An API key of the organization, or a short-lived preview link. A browser cannot send a bearer header, so this is the mode for a private page people open: a preview pane, a demo, a review link. |
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.
Private preview links, inside an iframe
pilot url update --auth token preview
pilot url token preview --ttl 1h --path /app
pilot url revoke preview
A preview link is the machine's own address with a signed token on a handshake path. Opening it sets a cookie for that one hostname and redirects to the path you asked for, so the page, its scripts and stylesheets, its fetches and its WebSockets, hot reload included, all work from then on. The cookie is HttpOnly, Secure, SameSite=None and partitioned, which is what lets it work inside an iframe on your own site without being a third-party tracking cookie.
// On your server, with an API key that never reaches the browser:
const { url } = await pilots.machines.previewToken(machineId, { ttl_s: 3600, path: '/' })
// In your page:
<iframe src={url} />
- A link lasts an hour by default and a day at most. Mint a fresh one each time you render the frame. It costs nothing and needs no cleanup.
pilot url revokekills every link minted so far, on every host, and links minted afterwards work. Destroying the machine kills them too.- A link is checked before a sleeping machine is woken, so an unauthorized request never wakes anything.
- The cookie, the
__pilots_tokenquery parameter and the token itself are removed before the request reaches your app. The path/__pilots/authis the router's and never reaches it either. - A cookie belongs to one hostname. A dev server whose hot reload listens on a second
port (a
<port>-<name>address) needs a link minted with that port, or the token as?__pilots_token=on that connection.
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
pilot domain addrecords the hostname and answers with the record to create at your registrar.- You create the record. DNS takes minutes, and there is nothing to poll.
pilot domain lsshows the name as verified once it resolves, and a certificate is issued for it. Unverified names are checked again every minute, and adding the name again checks it at once.- The service then serves on both its own address and yours. The original keeps working.
- The record for a subdomain is a CNAME onto the service's own address. A root domain
such as
example.comcannot carry a CNAME, so give it an ALIAS (ANAME, or a CNAME at the root where the DNS provider flattens it, as Cloudflare does) onto the same address, or A records onto the addresses that address resolves to. The ALIAS keeps working when a host joins or leaves the fleet. A records have to be updated then. - A proxy in front of the name (Cloudflare's orange cloud) hides the fleet's addresses, so the name never verifies and no certificate is issued. Set the record to DNS only.
- Adding a verified name again keeps it verified, so a retry never takes a live domain off the router.
- 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.
Every address of your team on your domain
A team can name one domain it owns, and every machine and service of the
team is then shown at <name>.apps.example.com and
<port>-<name>.apps.example.com. One wildcard certificate covers them all, and
Pilots obtains and renews it.
pilot org domain set apps.example.com
pilot org domain
pilot org domain setrecords the domain and answers with two records to create:*.apps.example.comas a CNAME onto the API hostname, and_acme-challenge.apps.example.comas a CNAME onto a name Pilots gives you.- You create both, DNS only. The second lets Pilots answer the certificate challenge without access to your DNS.
pilot org domainshows the domain as live once both resolve. They are checked again every minute, and setting the domain again checks them at once.
- It only adds an address.
<name>.<fleet domain>keeps answering, so a link already shared never breaks, and removing the domain puts the addresses back. - Only your team's machines and services answer under your domain. No other team can take the domain or attach a custom domain under it.
- Use a domain of its own for the apps your team runs, not the one your product signs
people in on: an app under
apps.example.comcan set cookies forexample.com.
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.