runlot docs

runlot domain add app.example.com

Running the command tells you which DNS records to create.

Add these two lines to your DNS:

  CNAME  app.example.com  →  apps.runlot.app
  TXT    _runlot-verify.app.example.com  →  <token>

The CNAME connects your app and the TXT record verifies domain ownership. Once your DNS changes have propagated, run `runlot domain verify app.example.com` to check right away; the system also checks automatically every minute.

With only the TXT record, ownership is verified but traffic won't reach your app. Create both the CNAME and the TXT record.

A domain bought through runlot

If you bought the domain through runlot, runlot hosts its DNS and writes the records for you. runlot domain add says there is nothing to add; the certificate is issued automatically, usually within a few minutes.

A root domain

DNS does not allow a CNAME at a root domain (example.com, as opposed to app.example.com). For a root domain the command asks for an A record instead:

  A      example.com  →  <address>
  TXT    _runlot-verify.example.com  →  <token>

If your DNS provider supports ALIAS, ANAME or CNAME flattening at the root, you can point the root at apps.runlot.app there instead of the A record.

Viewing status

runlot domain list

Host                  Type     Status
app.example.com       custom   connected
my-app.me.runlot.app  default  connected

The default row is the address every project gets.

Status	Meaning
`verifying`	Waiting for the DNS records to propagate.
`issuing certificate`	Ownership is verified and the TLS certificate is being issued. If an attempt failed, the reason and the time of the next attempt appear under the row.
`connected`	Your app is reachable at this address.
`error`	`runlot domain list` shows the reason for the error.

Traffic is only routed to addresses whose status is connected.

Checking right away

runlot domain verify app.example.com

The system checks automatically every minute. If you just created the DNS records, use this command to check immediately. While a certificate waits to be tried again after a failure, this command also moves the next attempt forward, to a minute after the last one.

A record you just created can take up to about 5 minutes to show at public DNS resolvers, because they may still remember the name as missing.

Disconnecting

runlot domain rm app.example.com

The command asks for confirmation. Once disconnected, your app is no longer reachable at that address.

TLS

TLS certificates are issued and renewed automatically. There is nothing for you to manage.

Restrictions

A project connects 1 custom domain on Free and 50 on Pro. The 51st is refused with 409 hostname_limit, and the response carries the limit, the current count and the plan. Re-sending a name the project already has is not refused — it answers with the existing record.
You cannot connect *.runlot.app or *.runlot.dev subdomains.
Wildcard hosts (*.example.com) are not supported.
Internationalized domains are normalized to punycode.
Custom domains are HTTP only. For psql, connect to the project's wire address (<project>--<org>.wire.runlot.app) instead of your custom domain.

Why ownership is verified separately

Without TXT ownership verification, someone could register a domain they don't own before its real owner does. To prevent that, runlot verifies domain ownership as an additional step.

Custom domains

On this page