DOMAIN(1)General Commands ManualDOMAIN(1)

domain — your own hostname for a VM's web page

ssh chroot.dev domain add host name

ssh chroot.dev domain ls

ssh chroot.dev domain rm host

A custom domain is a hostname of your own, such as ‘example.com’ or ‘app.example.com’, that leads to the VM's page as https://name.chroot.run does: the same port behind the proxy, the same access; see share(1). Once its DNS records pass the checks it gets a certificate of its own, from Let's Encrypt.

It belongs to the account, not to the VM: renaming the VM keeps it, and removing the VM leaves it in the account, leading nowhere, until add points it at another VM. A hostname is held by one account at a time, the first whose records pass; while it holds it, add of that hostname by another account fails with ‘held by another account, free once theirs is removed or has failed’.

host name
Lead host to the VM name and print the DNS records to create. A host the account has already moves to that VM, with its status and certificate.
Each custom domain with its VM, or ‘-’ for none, and its status; below the table, for each one whose last check failed, a line that names the record to fix, or says the hostname is held by another account, with a reference. Also list.
host
Remove it from the account. Its certificate is deleted, not revoked, and HTTPS to it stops within seconds. Also remove.

A hostname is lowercase, has two labels at least, labels of a-z, 0-9 and -, at most 63 characters each and 253 in all, and no trailing dot; an internationalized one goes in its ‘xn--’ form. Wildcards, IP addresses, chroot.run, chroot.dev and the names under them are refused. ‘www.example.com’ is a custom domain of its own, added apart from ‘example.com’.

The plan sets how many custom domains the account may have; past that, add fails with ‘account limit’. On a smaller plan the account keeps those it has.

Create them where the DNS of host is managed; add prints them, with the values for host.

host TXT proof
The proof that the account controls host, a value starting with ‘fcm-proof=’. It is read at that name only: the proof of ‘example.com’ does not count for ‘app.example.com’.
host A 51.161.12.93
At the apex of the zone, such as ‘example.com’, where a CNAME cannot be.
host CNAME name.chroot.run
Below the apex, such as ‘app.example.com’. An A to 51.161.12.93 works there too.

The checks also want:

  • no other A record for host;
  • no AAAA record: the proxy has no IPv6 address;
  • CAA: the closest name from host up that has CAA records must allow letsencrypt.org, as ‘0 issue "letsencrypt.org"’ does; with none, nothing to do.

At a DNS provider that proxies traffic, set the record to DNS only: host must resolve to 51.161.12.93 itself.

pending
Added, not checked yet. Also one whose records passed while another account holds the hostname: ls says ‘held by another account, free once theirs is removed or has failed’, and there is no record to fix. It is checked again as a failed one is, and is active at the first check after the hostname is free.
active
The records passed. It leads to the VM once its certificate is issued, usually within a minute.
failed
A check failed; ls says which record. It is not final: it is checked again 2 minutes later, then after 10 and 30, then after 1, 2, 4 hours and so on, up to once a day. add again, once its records are fixed, checks it at once, or 2 minutes after its last check if that was less than 2 minutes ago; failing again, it is checked after 10 minutes, then 30, and so on.

An active custom domain is checked again every day. When its records stop passing, it keeps working for 7 days, and ls shows what is wrong; fixed within them, nothing changes. After 7 days it is failed, its certificate is deleted and another account can take the hostname.

One whose VM was removed answers 404 ‘unknown name’. One without a certificate, not active yet or failed, refuses the TLS connection.

Lead ‘app.example.com’ to the VM web:

$ ssh chroot.dev domain add app.example.com web
app.example.com: pending, leads to web
create at its DNS:
  _chroot.app.example.com          TXT   fcm-proof=0f3c...
  app.example.com                  CNAME web.chroot.run
or, where a CNAME cannot be: app.example.com A 51.161.12.93
domain ls shows when it is active

Create the two records, then:

$ ssh chroot.dev domain ls
HOST                             VM               STATUS   REF
app.example.com                  web              active   -

Checked before the CNAME was there:

$ ssh chroot.dev domain ls
HOST                             VM               STATUS   REF
app.example.com                  web              failed   5e0a71c2
app.example.com: A app.example.com: none, 51.161.12.93 wanted (ref 5e0a71c2)

browser(1), share(1), website(7)

chroot.devOctober 14, 2026DOMAIN(1)