Domains

How your project gets its web address — from a free subdomain to your own root domain, without touching a DNS console.

Machine-readable API reference: /llms-full.txt · /openapi.json

Managed subdomains — yourname.run402.com

Every project can claim a free subdomain. It is usually claimed for you as part of a deploy, serves over HTTPS immediately, and follows every future deployment automatically — no DNS, no certificates, nothing to renew.

run402 subdomains claim yourname --project prj_...

• 3–63 characters, lowercase letters, digits, and hyphens.
• Stays yours while the project is active (and is reserved for you through billing grace periods).
• Keeps working after you add a custom domain — it is the always-on fallback address.

Custom domains — yourdomain.com

A custom domain attaches to the same project and serves the same deployments, with its own automatically provisioned TLS certificate. There are two ways to connect one; for root domains (yourdomain.com rather than www.yourdomain.com) the hosted option is strongly recommended, because most DNS hosts cannot point a root domain at a hostname at all.

Option 1 (recommended): Run402-hosted DNS — one nameserver change

Run402 hosts the domain's DNS zone for you. The only thing the domain owner ever does is change the nameservers at their registrar — Run402 applies every DNS record, verifies ownership, and issues the certificate automatically once the change is seen. Works from any registrar: GoDaddy, Namecheap, Route53, anywhere.

Connect the domain (CLI run402 v4.24.0+):

run402 domains connect yourdomain.com --project PROJECT_ID --web --authority hosted-zone

Or over plain HTTP, with any control-plane credential including the project's own service key:

curl -X POST "https://api.run402.com/projects/v1/PROJECT_ID/domains/yourdomain.com" \
  -H "Authorization: Bearer SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"desired":{"authority":"hosted_dns_zone","web":{"enabled":true}}}'

The response's hosted_zone.ns_assigned lists two nameservers. Hand the domain owner exactly one instruction:

• Email is preserved. Existing MX and TXT records are copied into the hosted zone before the nameserver change is recommended, so mail on the domain keeps flowing.
• Progress is visible. Run run402 domains wait yourdomain.com --until active (or poll the same URL / POST .../actions/check) until status is active; the zone.delegation check tracks the nameserver change. A background sweep completes activation even if nobody polls.
• Reversible. Disconnecting (DELETE) tears the hosted zone down — the response warns that DNS stops resolving until the nameservers are re-pointed.

Option 2: Manual DNS — keep your current DNS host

If the domain owner prefers to keep DNS where it is, connect without the authority field and the response's dns_records[] lists exactly which records to add (with copy-paste BIND lines). This works well for subdomains like app.yourdomain.com; for root domains it requires a DNS host that supports CNAME flattening or ALIAS records (Cloudflare does; most registrars' default DNS does not — use Option 1 instead).

run402 domains connect app.yourdomain.com --project PROJECT_ID --web

Or over plain HTTP:

curl -X POST "https://api.run402.com/projects/v1/PROJECT_ID/domains/app.yourdomain.com" \
  -H "Authorization: Bearer SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"desired":{"web":{"enabled":true}}}'

Which one do I want?

	Hosted DNS (Option 1)	Manual DNS (Option 2)
Root domain (yourdomain.com)	Works everywhere	Only on flattening/ALIAS-capable DNS hosts
Owner's work	One nameserver change	Add each listed record
DNS stays at current host	No (Run402 hosts the zone)	Yes
Later records (email, verification)	Applied automatically	Added manually

One surface handles everything: /projects/v1/:project_id/domains/:domain covers connect, status, DNS records, health checks, repair, and disconnect for web and email alike. Full contract in the API reference; agents get the same instructions there.