Skip to main content
Every HTTP listener gets a generated https://... URL on a Sail domain. With a custom domain, the same listener also answers on a hostname you own, such as app.example.com. Sail obtains and renews the TLS certificate for you. There is nothing to upload and no certificate to manage.

​
Add a custom domain

Adding a domain is a three step process.

​
1. Expose an HTTP listener

Expose the guest port as an HTTP listener, at creation time or later. See Networking for details.

​
2. Point your domain at your target address

Every organization has its own target address under sailboxes.sailresearch.com. Pointing your domain at it is what proves your organization controls the domain, so no one else can register it. Find your target in the cname_target field of the list call below, or in the error message if you register before DNS is ready. Create a CNAME record at your DNS provider:
For an apex domain like example.com, standard CNAME records are not allowed at the zone root, and ALIAS-style records hide the target name. Use your provider’s ALIAS or ANAME record type for routing, and add a TXT record that carries the proof instead:
Some DNS providers proxy or accelerate traffic for a record by default. Turn that off for this record. The record must resolve directly to the Sail target. These records are your standing authorization: any record that names a target keeps authorizing that organization. If you switch organizations or stop using Sail, remove the old records.

​
3. Register the domain

Register the domain against the Sailbox and guest port. Sail checks that the DNS record is in place, then starts serving the hostname:
If the DNS record has not propagated yet, registration fails with instructions. Wait for propagation and try again. The TLS certificate is issued on the first HTTPS request to the domain. That first request can take up to a minute while the certificate is obtained; after that, requests are served immediately. Certificates renew automatically for as long as the domain stays registered and the DNS record stays in place. Plain HTTP requests to the domain redirect to HTTPS.

​
List and remove domains

The list response includes your organization’s cname_target, so you can look it up before registering your first domain.
Removing a domain stops routing and certificate renewal for it. Removing the listener the domain points at removes its domains too.

​
Notes

  • A domain can be registered to one Sailbox listener at a time.
  • Wildcard domains such as *.example.com are not supported. Register each hostname individually.
  • Custom domains apply to HTTP listeners. TCP listeners already work with any hostname you CNAME at their endpoint, because TCP connections are routed by port and passed through without TLS termination.
  • Listener allowlists keep working behind a custom domain.
  • The domain keeps working across sleep and resume. A request to a sleeping Sailbox wakes it, like on the generated URL. While a Sailbox is paused, its domains stay registered but requests fail until you resume it. Terminating the Sailbox stops its domains.
  • On a private Sailbox, only its creator can add or remove domains.