Skip to main content
Custom domains make it possible to serve an HTTP listener running in a Sailbox on a hostname you own, in addition to the generated https://sb-<...>.sail.box URL every listener gets. Sail obtains and renews the TLS certificate for you.

​
Add a custom domain

​
1. Expose an HTTP listener for a Sailbox

To expose port 3000 for HTTP traffic from the CLI:
See Networking for details on what this command does.

​
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. Find your target with:
Command
Create a CNAME record with your DNS provider:
Cloudflare (and some other DNS providers) proxy/accelerate traffic. Turn that off for this record. On Cloudflare, set the record to “DNS only” so the orange proxy cloud is off.

​
Optional: Wildcard records

If you anticipate attaching many subdomains to Sailboxes, you should use wildcard DNS records.
  • The first record sends every direct subdomain to Sail (app.example.com would work, but hello.app.example.com would not)
  • The second record lets Sail create one wildcard certificate for them. This is optional: if it is not set, we issue one certificate per subdomain, which risks hitting certificate issuance rate limits (see Notes)
  • Attach each hostname to a Sailbox. Do not attach *.example.com.

​
Root/apex domains like example.com

Standard CNAME records are not allowed for apex domains. Different DNS providers provide different solutions: look for an ALIAS, ANAME, or CNAME flattening option. In addition to an apex record, Sail needs a TXT record for verification. Overall, the setup looks like:

​
3. Add the domain to your Sailbox

Attach the domain to the Sailbox and port. Sail checks that the DNS record is in place, then starts serving the hostname:
--port is required and must identify an exposed HTTP listener. You can also do this in the Sailbox dashboard under “Network Listeners.”

​
List, remove, and replace domains

Detaching a domain stops routing it to the Sailbox. Attaching a domain to a different Sailbox detaches it from the old Sailbox automatically.

​
Custom domains for TCP listeners

All the setup listed on this page is for HTTP listeners. If you have a raw TCP endpoint that you wish to point a custom domain at, you do not need to register the domain with Sail. Just add a DNS record:
Then dial foo.example.com:<port of tcp listener>.

​
Notes

  • An organization can attach up to 200 total domains. If your use case needs more than that, reach out to us: support@sailresearch.com
  • The certificate provider we use, Let’s Encrypt, allows 50 new certificates per apex domain every 7 days. That limit is global for your domain, not specific to Sail. It is highly recommended that you use the wildcard _acme-challenge verification listed in Optional: Wildcard records, and that you contact us if your use case requires large numbers of subdomains.
  • A domain serves one Sailbox listener at a time, but one listener can have multiple domains (for example, foo.example.com and bar.example.com can both point at the same listener)
  • Removing a listener also detaches all of the domains registered to it. Terminating a Sailbox stops serving its domains, but they stay attached and count toward the domain limit until you detach them or attach them to another Sailbox.
  • DNS records prove your organization owns a domain. If that is no longer the case, you should delete these records.
  • It takes up to 1 minute for Sail to obtain a valid certificate for your domain. If you make a request in the first minute after you attach a domain, you may see higher latency.
  • All the features of Sailbox networking still work under a custom domain:
    • A request to a sleeping Sailbox wakes it.
    • Plain HTTP requests to the domain redirect to HTTPS.
    • Listener allowlists keep working.