Custom Domains

Serve a Sailbox HTTP listener on your own domain

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:

sail box expose $SAILBOX_ID 3000

See Access Control 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 proves your organization controls the domain. Find your target with:

Command

sail box domain target
# Output:
# CNAME target: 1a2b3c4d5e6f7890.sailboxes.sailresearch.com
# Wildcard certificate target: 1a2b3c4d5e6f7890._acme-challenge.sailboxes.sailresearch.com

Create a CNAME record with your DNS provider:

app.example.com  CNAME  1a2b3c4d5e6f7890.sailboxes.sailresearch.com

Cloudflare (and some other DNS providers) proxy/accelerate traffic. Turn that off for this record. On Cloudflare, set the record to “DNS only”.

Optional: Wildcard records

If you expect to attach many subdomains to Sailboxes, you should use wildcard DNS records.

*.example.com                  CNAME  1a2b3c4d5e6f7890.sailboxes.sailresearch.com
# optional, but recommended
_acme-challenge.example.com    CNAME  1a2b3c4d5e6f7890._acme-challenge.sailboxes.sailresearch.com

• 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. Each DNS provider handles this differently: look for an ALIAS, ANAME, or CNAME flattening option.

Besides the apex record, Sail needs a TXT record for verification. The setup looks like this:

# Apex record
example.com                 <ALIAS/ANAME/CNAME>  <your-target>.sailboxes.sailresearch.com
# Additional TXT verification record
_sail-domains.example.com   TXT                  <your-target>.sailboxes.sailresearch.com

Apex Record by DNS provider

DNS provider	Apex option
Cloudflare	CNAME, flattened at the apex automatically
Namecheap	ALIAS
DNSimple	ALIAS
DNS Made Easy	ANAME
Porkbun	ALIAS
Amazon Route 53	None for external targets (ALIAS records can point only to AWS resources). Serve on a subdomain such as www instead.
Azure DNS	None for external targets (alias records can point only to Azure resources). Serve on a subdomain such as www instead.
Google Cloud DNS	None. Serve on a subdomain such as www instead.

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:

sail box domain attach $SAILBOX_ID app.example.com --port 3000
# Output:
# Attached app.example.com to sb_... on guest port 3000
# https://app.example.com

--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

# List the domains attached to a Sailbox.
sail box domain list $SAILBOX_ID
# Output:
# DOMAIN           GUEST_PORT  URL                      CREATED_AT
# app.example.com  3000        https://app.example.com  2026-08-01T00:00:00Z

# Attach a domain to a different Sailbox (it is automatically detached from its current Sailbox)
sail box domain attach $OTHER_SAILBOX_ID app.example.com --port 3000

# Detach a domain from a Sailbox.
sail box domain detach $OTHER_SAILBOX_ID app.example.com

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 want to point a custom domain at, you do not need to register the domain with Sail. Add a DNS record:

foo.example.com CNAME t1.sail.box

Then dial foo.example.com:<port of tcp listener>.

Notes

• An organization’s attached hostnames can use up to 200 distinct certificate names. All hostnames sharing one wildcard certificate count as one, regardless of how many you attach. Hostnames using individual certificates count separately. A slot is reserved when a hostname is attached, even before its certificate is ready. If you need more than 200 distinct certificate names, reach out to us.

• Each organization can start up to 30 new certificate attempts in a burst. The allowance recovers by one attempt every 6 minutes, up to 30. Failed attempts count toward this allowance. Certificate renewals and additional hostnames that reuse an existing wildcard certificate do not count. A new hostname can take longer to become available when this allowance is exhausted. Hostnames that are already serving are unaffected.

• Concurrent attachment requests can receive HTTP 429. Retry after the interval in the Retry-After response header. A temporary failure checking certificate DNS returns HTTP 503 and can also be retried.

• 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 retain their certificate slots. A slot is freed when none of your organization’s attached hostnames uses that certificate.

• DNS records prove your organization controls 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.