Custom Domains

Bring your own hostname. Run your previews under app.acme.com instead of nexos.rs, or attach a wildcard apex so every branch gets its own subdomain under your company's domain.

The two binding kinds

Nexos supports two shapes — pick whichever matches how you want your previews to be addressed.

The two kinds aren't exclusive. A project can have both — for example app.acme.com pinned to your main environment and preview.acme.com covering every feature branch.

Adding a domain

1. Open your project in the dashboard and click Domains in the sub-navigation.
2. Pick a kind — Wildcard apex or One environment — and type the hostname (no scheme, no port, no path).
3. For an environment binding, pick the target environment and, optionally, a specific service within it.
4. Click Add domain. The row appears with status Pending DNS.

DNS setup

Each new domain comes with two records you publish at your DNS provider. One proves you own the hostname; the other actually routes traffic to Nexos.

1. Ownership — TXT record

Add a TXT record so Nexos can confirm you control this domain. The dashboard shows the exact name and value — copy them as-is.

Type:   TXT
Name:   _nexos-challenge.<your-hostname>
Value:  nexos-verify=<token>

Once the TXT record has propagated, click Verify on the row. Nexos performs a live DNS lookup and flips the status to Verified on a match. Verification is idempotent — safe to retry as many times as you need.

2. Routing — CNAME (or wildcard CNAME)

Add a CNAME from your hostname to the Nexos preview proxy. The exact target depends on the operator running your Nexos instance — on the managed platform that's the value displayed on the row, typically a preview. subdomain of the platform domain.

Environment FQDN

Type:   CNAME
Name:   app.acme.com
Value:  preview.nexos.rs

Wildcard apex

Type:   CNAME
Name:   *.preview.acme.com
Value:  preview.nexos.rs

Some registrars don't support wildcard CNAMEs. In that case use a wildcard A record pointing at the proxy's IPv4 (and AAAA for v6).

TLS certificates

Nexos issues TLS certificates on demand for verified custom domains. You don't configure anything — the first HTTPS request to your domain triggers issuance via Let's Encrypt, and the cert is then cached and auto-renewed.

Environment FQDNs issue cleanly using the standard HTTP-01 / TLS-ALPN challenges. A wildcard *.acme.com cert needs DNS-01, which is configured on the operator side. If your Nexos operator hasn't enabled DNS-01, apex bindings still route HTTP traffic but won't serve TLS for the wildcard — prefer environment FQDNs in that case.

How requests get routed

When a browser hits your custom domain, Nexos resolves it against your project in this order:

1. Exact match — the hostname is registered as an environment-type custom domain (and verified). Traffic goes to that environment, optionally narrowed to a specific service.
2. Apex suffix match — the hostname ends with a registered apex. The leftmost label is treated as an environment slug (or <service>-<env-slug> for multi-service URLs) within the apex's project.
3. Platform preview — falls back to the regular <env-slug>.nexos.rs resolution if nothing custom matched.

Unverified rows are skipped entirely — your domain has no effect on routing until the TXT challenge passes.

Examples

Stable URL for a hosted service

Run app.acme.com directly on Nexos. Pin it to your production environment so every push to main keeps the URL pointed at the latest deploy.

# In the Domains tab:
Hostname: app.acme.com
Kind:     Environment
Target:   production

# DNS:
_nexos-challenge.app.acme.com   TXT     "nexos-verify=…"
app.acme.com                    CNAME   preview.nexos.rs

Branded preview URLs for every branch

Make every feature branch reachable at <branch>.preview.acme.com instead of the default Nexos hostname.

# In the Domains tab:
Hostname: preview.acme.com
Kind:     Wildcard apex

# DNS:
_nexos-challenge.preview.acme.com   TXT     "nexos-verify=…"
*.preview.acme.com                  CNAME   preview.nexos.rs

# Result:
git push origin feature/new-checkout
# → https://feature-new-checkout-….preview.acme.com

Multi-service projects work the same way: api-feature-new-checkout.preview.acme.com reaches the api service of that environment.

Removing a domain

Click the trash icon on the row. The hostname is immediately released — anyone (including you) can re-register it. TLS material is cleaned up automatically on the next ACME refresh cycle.

Troubleshooting

• "No TXT record found at _nexos-challenge.…" — DNS hasn't propagated yet, or the record is on the wrong label. Try dig TXT _nexos-challenge.your-host.com from your terminal first; the value should match exactly what the dashboard shows.
• "Expected TXT value 'nexos-verify=…' at …" — the TXT record exists but holds a different (or stale) value. If you deleted and re-created the domain, the token changed — copy the new value.
• Verified but the URL still 404s. Confirm the CNAME points at the right target and that you have an environment whose slug matches the leftmost label (for apex bindings). Reserved subdomains (www, api, app, etc.) are ignored on the platform domain but allowed under your own apex.
• TLS cert errors right after verification. The first request triggers issuance, which takes a few seconds. Subsequent requests serve the cached cert.

API

Same operations are available programmatically — useful for managing domains as part of an IaC workflow.

# List domains for a project
curl https://api.nexos.rs/projects/:projectId/domains \
  -H "Authorization: Bearer nxs_..."

# Add a wildcard apex
curl -X POST https://api.nexos.rs/projects/:projectId/domains \
  -H "Authorization: Bearer nxs_..." \
  -H "Content-Type: application/json" \
  -d '{"hostname":"preview.acme.com","type":"apex"}'

# Add an environment FQDN bound to a specific service
curl -X POST https://api.nexos.rs/projects/:projectId/domains \
  -H "Authorization: Bearer nxs_..." \
  -H "Content-Type: application/json" \
  -d '{"hostname":"app.acme.com","type":"environment","environmentId":"…","serviceId":"…"}'

# Re-check DNS verification
curl -X POST https://api.nexos.rs/domains/:domainId/verify \
  -H "Authorization: Bearer nxs_..."

# Delete a domain
curl -X DELETE https://api.nexos.rs/domains/:domainId \
  -H "Authorization: Bearer nxs_..."

See also: Projects, Deployments, Resource Limits & Quotas.