Skip to main content
Every machine already gets <machine>.boxd.sh automatically. See HTTPS. Custom domains let you put your own domain in front of it instead, in two ways:
  • Per-machine. Point one domain you own at a single machine, for example myapp.mysaas.com.
  • Org-wide. Delegate a wildcard subdomain to your whole organization, so every machine gets its own name under it, for example myapp.vms.mysaas.com and myapp2.vms.mysaas.com.
Both are self-serve. boxd verifies your DNS and issues TLS certificates automatically. You can also set the domains on the Domains page of the console, and from the Python and TypeScript SDKs.

Per-machine

1

Start adding the domain

This doesn’t touch anything on the server yet. It just prints the two DNS records to add:
The A record’s target is the same shared address myapp.boxd.sh already resolves to (boxd machine get myapp shows it too). The wildcard CNAME is required even if you don’t plan to use subdomains yet, because it’s how the certificate gets issued (see below).The hosts leave out mysaas.com, because most DNS editors add it themselves: typing myapp.mysaas.com there creates myapp.mysaas.com.mysaas.com. If yours asks for full names, use myapp.mysaas.com and *.myapp.mysaas.com. For a whole domain (boxd machine domain add mysaas.com), the hosts are @ and *.
2

Add those records at your registrar

Add them where your domain’s DNS is hosted (usually your registrar), exactly as printed, and nothing else. Delegating NS records belongs to the org-wide flow below, so skip that here.
3

Confirm

The same command is still paused in your terminal, waiting for you. Once the records are live, press Enter. Only then does boxd start checking and create anything server-side.In a script, pass -y/--confirm up front and it skips the wait. Only do this once the records are live:
The domain starts pending and a background check verifies DNS and issues the certificate, typically within a minute or two of the records actually resolving. Once both the apex and wildcard certs exist, it flips to active and starts routing.
Add the DNS records before you test the domain. A resolver that looks up the domain too early caches the “this doesn’t exist” answer, and that cached answer can outlive your fix. So a correct setup can look broken on your network even while the console shows active. If that happens, try another network or resolver, for example 1.1.1.1 or 8.8.8.8 under your browser’s secure DNS setting.

Org-wide wildcard domain

Each org gets one domain, and the wildcard covers every machine, current and future, with no per-machine step.
1

Start setting the domain

This prints the NS records to delegate:
2

Delegate at your registrar

These are NS records. Adding them at your registrar hands DNS authority for vms.mysaas.com to boxd, the same way mysaas.com as a whole is delegated to your DNS provider. From then on, boxd answers DNS for every name under vms.mysaas.com and issues the wildcard certificate, with nothing else to add on your side. Delegate only this one subdomain. Everything else on mysaas.com stays with your current DNS setup.As with the per-machine records, the host is vms, not vms.mysaas.com, unless your DNS editor asks for the full name.
3

Confirm

The same command is still paused in your terminal. Press Enter once delegation is live. For scripts, pass -y/--confirm up front instead:
Using a whole domain? If the org domain is one you registered itself (mysaas.com, not a subdomain of it), it can’t be delegated with NS records. boxd manage domain set then tells you to set its nameservers to ns1.boxd.sh and ns2.boxd.sh at your registrar (Namecheap calls this Custom DNS; elsewhere it’s custom nameservers). That moves all of the domain’s DNS to boxd, so its other records, such as mail, stop being served.
Until boxd sees the delegation in public DNS, the domain stays pending. boxd checks every minute, and a nameserver change usually shows within minutes, occasionally only after a day or more. Once active, every machine in the org is reachable at <machine>.vms.mysaas.com in addition to <machine>.boxd.sh. The default domain never stops working. The bare wildcard domain itself (vms.mysaas.com with no machine name) doesn’t route anywhere, since there is no “default machine” for it.

Regions

A machine in New York has its address under that region’s zone, such as myapp.nyc.boxd.sh. boxd machine domain add prints records that point there, so the wildcard CNAME targets myapp.nyc.boxd.sh. An org has one wildcard domain in each region. Each covers the org’s machines in its region and is delegated to that region’s nameservers, ns1.nyc.boxd.sh and ns2.nyc.boxd.sh for New York. One region’s domain can’t be the same as, inside, or around another’s, so give each region a name of its own:
Name the region when you set one. Without --region, manage domain acts in the region the CLI picks for machines. In the console, setting the wildcard domain asks which region it’s for.