Skip to content
pilots
Dashboard
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 revoke kills 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_token query parameter and the token itself are removed before the request reaches your app. The path /__pilots/auth is 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
  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. Unverified names are checked again every minute, and adding the name again checks it at once.
  4. 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.com cannot 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
  1. pilot org domain set records the domain and answers with two records to create: *.apps.example.com as a CNAME onto the API hostname, and _acme-challenge.apps.example.com as a CNAME onto a name Pilots gives you.
  2. You create both, DNS only. The second lets Pilots answer the certificate challenge without access to your DNS.
  3. pilot org domain shows 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.com can set cookies for example.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.