Custom domains

A box can answer at your own domain, https://example.com, as well as at its kvbox.app address. kvbox serves it through the same edge and gets its certificate from Let's Encrypt.

Add the domainCopy Anchor Link

kvbox domain add example.com lab1
# ✓ example.com added for box lab1 port 3000, waiting for its DNS
#
# At the company that runs the DNS of example.com, add:
#
# TYPE   HOST    VALUE
# A      @       65.21.146.225
# TXT    _kvbox  kvbox-verify=3f9c…
# CNAME  www     example.com

The domain serves the same port as the box's HTTPS address. A box without one, or a different port, takes --port:

kvbox domain add app.example.com lab1 --port 8080

Set the recordsCopy Anchor Link

Add the records exactly as printed, where your domain's DNS is managed (usually where you bought it). The HOST is what goes in the editor's host (or name) field: @ for example.com itself, www for www.example.com, and for app.example.com it is app and _kvbox.app.

• The A record sends the domain to kvbox. It works for a bare domain like example.com as well as for a name under it.
• The TXT record shows the domain is yours: its value is your own, for this domain. Keep it: a domain that goes back to pending needs it again to be live.
• The www record is optional. With it, www.example.com serves the same site, on the same certificate.

Only these records change. Your email and other records stay where they are, except an AAAA record for the same name: kvbox serves IPv4 only, so delete it, or the domain stays pending.

LiveCopy Anchor Link

kvbox checks the DNS every minute. Once the A record points here and the TXT record is set, the domain is live, and its certificate is made on the first visit, in a few seconds:

kvbox domain ls
# DOMAIN                  BOX    PORT  STATUS       NOTE
# example.com (+www)      lab1   3000  live         https://example.com
# app.example.com         lab1   8080  pending dns  app.example.com has no A record yet (set it to 65.21.146.225)

Only the account whose TXT record the domain holds can make it live, so nobody can put your name on their box. If someone added your domain before you, set your TXT record and run kvbox domain add again: it becomes yours. A domain is served only while it points at kvbox; if it stops pointing here, it goes back to pending until it does again, with its TXT record set.

A domain that stays pending for 3 days is removed, and the name is free again. Once your records are set, run kvbox domain add again.

DNS changes can take a while to reach everyone. If the domain is live but your browser still cannot find it, your network may have kept the old answer: try another network, or a public resolver like 1.1.1.1.

Remove itCopy Anchor Link

kvbox domain rm example.com

The box keeps running and keeps its kvbox.app address; you can delete the DNS records. Removing the box removes its domains too.

A user or an org can have up to 5 domains. Like the HTTPS address, a visit wakes a hibernated box, and anyone who has the address can reach it.