Adding a Custom Domain to Your Project

Every Orbit project serves on a free kaps.run address, and you can attach your own domains alongside it with an SSL certificate provisioned automatically. This guide covers adding a domain, the DNS record you need, how to read the verification states, choosing a primary domain, and what to check when a domain stays stuck.

Before You Start

You need an Orbit project with at least one successful deployment, a domain you control the DNS for, and a plan that includes custom domains. Custom domains are included on Liftoff and Apex; the free Launch plan does not include them. See Orbit Plan Limits.

Step 1: Add the Domain In Orbit

Open your project in Orbit.
Open the Domain tab, or click Manage domains from the Custom domains card in Settings.
Under Add a domain, type the hostname, for example app.example.com.
Click Add.

Enter a plain hostname. Do not include https://, a trailing slash or a path: the form rejects anything that is not a bare hostname with "Enter a valid hostname like app.example.com".

Domain tab of an Orbit project

You can add up to 25 domains to a project. The first one you add becomes the primary domain.

If the domain is already attached to a different Orbit project, Orbit refuses it. Remove it from the other project first.

Step 2: Add the DNS Record

Orbit shows a DNS setup panel with the exact record to create: a CNAME, with the Name and Value to use. The target is the same whoever hosts your DNS.

If Your Domain Uses Kapsule DNS

Click Domains in the KPanel sidebar.
Click your domain.
In the DNS editor, add a CNAME record using the Name and Value shown on the Orbit Domain tab.

If Your Domain Uses Another DNS Provider

Sign in to that provider and add the same CNAME record. The interface differs, but the record type, name and value do not.

Apex domains (example.com with no subdomain) cannot take a plain CNAME under the DNS standard. Many providers offer CNAME flattening or an ALIAS or ANAME record that achieves the same thing; use that if yours does. If it does not, publish on a subdomain such as www.example.com and redirect the apex to it at your DNS provider or registrar.

Step 3: Wait For Verification and SSL

Orbit checks DNS on its own and the Domain tab reports where it has got to:

What you see	What it means
Checking DNS…	A check is running right now
CNAME not detected yet	The record has not propagated, or is not correct
CNAME verified: SSL provisioning…	The record resolves, the certificate is being issued
SSL active: CNAME verified	The domain is live and serving over HTTPS

Click Re-check DNS to force a check rather than waiting for the next automatic one.

DNS propagation takes anywhere from a few minutes to several hours depending on the TTL on your old records. The certificate issues within a minute or two of the CNAME being detected, and renews automatically for as long as the domain stays attached.

Before you add the record, lower the TTL on the existing record for that hostname and wait for the old TTL to expire. Cutting over then takes minutes rather than hours. This matters most when you are moving a live hostname rather than adding a new one.

Choosing the Primary Domain

With more than one domain attached, one is marked Primary. Click Set as primary domain on any verified domain to change it. The primary is the canonical address for the project; the others continue to serve.

Removing a Domain

Click Remove domain on the row.

Removing a domain takes it out of service immediately. Visitors stop reaching your project on that hostname straight away, and the certificate for it is no longer maintained. The DNS record at your provider is not removed: delete it yourself once you no longer need it, or it will keep pointing at a hostname that no longer answers for you.

Your project continues to serve on its kaps.run address regardless.

SSL Is Automatic and Free

You never buy, upload or renew a certificate for an Orbit domain. Once the CNAME resolves, a certificate is issued and then renewed automatically. There is no certificate management screen because there is nothing to manage.

Troubleshooting

Stuck on "CNAME not detected yet".

Check the record type. An A record pointing at an IP address does not verify; it must be a CNAME to the value Orbit gave you.
Check the record name. Many DNS editors append the zone for you, so entering app.example.com can produce app.example.com.example.com. Enter just app if the editor shows the zone as a suffix.
Check for a conflicting record. An existing A, AAAA or CNAME on the same name will win or make the zone invalid. Remove it.
Check you edited the zone that is actually authoritative. If you moved nameservers recently, you may be editing the old provider's copy.
Wait out the TTL of the record you replaced.

Verified, but the certificate does not activate. A CAA record on the domain can prevent issuance. Either remove it or add an entry permitting the certificate authority Kapsule uses. If you are not sure, contact support with the domain name.

"This domain is already attached to another project." Exactly what it says. Find the other Orbit project and remove the domain there first.

"Domain limit reached." You are at 25 domains on this project. Remove one you no longer need.

The domain resolves but shows the wrong site. Check the CNAME target character for character. It is easy to attach the domain to one project and point DNS at another.