Custom domains
Every project gets a docs address on Octri straight away. A custom domain puts your docs on your own hostname, which is what you want before you link to them from your site.
Your default address has a random ID in it, so a custom domain is the way to a branded URL, and that shouldn't depend on what you pay.
Setting one up
Open Project settings and choose Domains.
- Add the hostname
Enter the domain you want, such as
docs.acme.com. Octri shows the two records to create. - Add both records at your DNS provider
Type Name Value CNAMEdocsThe target Octri shows you TXT_octri-verify.docsThe token Octri shows you Some providers want the full name, such as
_octri-verify.docs.acme.com, and others add your domain for you. Check how your provider's other records look. - Verify
Choose Verify, or Re-check DNS after a failed attempt. Octri looks up both records through public DNS, and confirms the domain is yours.
Once verified, Octri registers the hostname and your docs serve from it over HTTPS. The certificate is issued and renewed for you.
Why two records
The CNAME sends traffic to Octri. The TXT record proves the domain is yours.
Anyone can point a CNAME at any host. If routing were the only requirement, someone could aim docs.your-competitor.com at their own Octri project. The TXT record ties the claim to whoever controls the DNS zone.
A root domain
To serve docs from acme.dev rather than docs.acme.dev, you can't use a CNAME, because DNS doesn't allow one at the root. Use your provider's ALIAS or ANAME record, pointed at the same target, plus the TXT record as usual.
Octri accepts this by comparing the addresses your hostname resolves to with the target's.
Cloudflare
Both proxied and DNS-only records work. A proxied record, with the orange cloud, hides the CNAME from public DNS, so Octri compares addresses instead.
Set the TXT record to DNS-only. Cloudflare doesn't proxy TXT records, so that's what it does by default.
Rules
| Rule | Why |
|---|---|
| One project per hostname | Includes claims not yet verified, so two projects can't race for a domain |
| Not a subdomain of Octri's docs domain | Those already resolve, and need no CNAME |
| Not a domain Octri serves | It would shadow Octri's own site |
| A valid hostname | Labels of 63 characters or fewer, 253 in all |
When verification fails
Each failure says what Octri found.
| Message | What it means | What to do |
|---|---|---|
CNAME for docs.acme.com points to ..., expected ... | The hostname has a CNAME, to somewhere else | Change its value to the target shown |
docs.acme.com does not resolve. Add a CNAME pointing to ... | Nothing points the hostname at Octri yet | Add the record, or wait for it to spread |
No TXT record found at _octri-verify.docs.acme.com | Octri can't see the record | Check the name. A common mistake is a doubled domain, such as _octri-verify.docs.acme.com.acme.com |
TXT record at ... does not contain the expected token | A record exists, with a different token | Replace it with the current token. Removing and re-adding the domain issues a new one |
DNS lookup failed for ... | DNS didn't answer | Try again shortly |
docs.acme.com is already claimed by another project | Another project holds it, possibly one you've forgotten | Remove it from that project first |
Waiting for DNS
Changes take time to spread. Verification checks what public DNS says right now, so if you've just added the records, wait and retry rather than entering everything again.
Some resolvers remember a failed lookup. If you verified too early, retries may keep failing until your zone's negative TTL runs out, even though the record is live.
To check for yourself:
dig +short CNAME docs.acme.com
dig +short TXT _octri-verify.docs.acme.comAfter it's live
- Your Octri address keeps working. The custom domain is an addition, so old links don't break.
- Search engines see your domain. Canonical URLs follow it, as SEO explains.
- Access control applies there too. See access control.
To add branding beyond the address, see white label.
Serving your MCP server
Your MCP server can have its own custom domain, separately from your docs.
From the CLI
You can add, verify and remove the domain with octri docs domain.