Custom Domains

Assign your own domain names to Clue2App applications. Every app gets a default URL like appname.namespace.apps.clue2.app, but you can add custom domains like api.example.com or www.mysite.com.

Clue2App supports two DNS methods:

Method	Setup	Per-subdomain DNS	Best for
DELEGATION (recommended)	One-time NS record setup	Automatic — no manual DNS per app	Teams managing multiple apps under one domain
CNAME_ONLY	No registrar changes	Manual — 2 CNAME records per subdomain	Quick setup for a single subdomain

Quick Start — DELEGATION (Recommended)

DELEGATION creates a dedicated DNS zone in AWS Route53. After a one-time NS setup at your registrar, all subdomains and TLS certificates are fully automatic.

1. Register your domain

c2a domain register example.com --method DELEGATION

This returns 4 NS (nameserver) records:

DNS Setup Required

Add these NS records at your domain registrar for example.com:

  1. NS  ns-888.awsdns-47.net
  2. NS  ns-1569.awsdns-04.co.uk
  3. NS  ns-1175.awsdns-18.org
  4. NS  ns-61.awsdns-07.com

2. Update nameservers at your registrar

Go to your domain registrar and replace the existing nameservers with the ones from step 1.

Replacing Nameservers

This transfers DNS control to Clue2App's Route53 zone. If you have existing DNS records (MX for email, A records for other services), you'll need to recreate them in Route53 before switching nameservers. Contact support if you need help migrating existing records.

Registrar-specific instructions:

GoDaddy

1. Go to My Domains → select your domain → DNS → Nameservers
2. Click Change Nameservers → Enter my own nameservers
3. Enter the 4 NS values from step 1
4. Click Save

Squarespace (Google Domains)

1. Go to Domains → select your domain → DNS → Nameservers
2. Switch to Custom nameservers
3. Enter the 4 NS values from step 1
4. Click Save

Namecheap

1. Go to Domain List → select your domain → Nameservers
2. Select Custom DNS
3. Enter the 4 NS values from step 1
4. Click the checkmark to save

Cloudflare

Cloudflare acts as both registrar and DNS provider. To delegate to Route53, you'd need to transfer the domain to a different registrar. Alternatively, use CNAME_ONLY mode with Cloudflare (see below).

3. Verify NS propagation

NS changes typically take 5–30 minutes. Verify with:

c2a domain verify example.com

Output when ready:

✓ All NS records verified! Domain is ready for use.
Subdomains will get automatic TLS certificates (~90s).

4. Add domains to your apps

c2a domain add --app frontend www.example.com
c2a domain add --app backend api.example.com

That's it — no manual DNS changes needed. Each subdomain gets:

• Automatic DNS record in Route53
• Automatic TLS certificate via Let's Encrypt (~90 seconds)
• Automatic Knative domain mapping

5. Check status

c2a domain assignments --app frontend

Status progression: Pending → DNS Verified → Issuing cert... → Live

---

Quick Start — CNAME_ONLY

For simple setups where you don't want to change nameservers. You manage DNS manually at your provider.

1. Register your domain

c2a domain register example.com

Or with the method explicitly:

c2a domain register example.com --method CNAME_ONLY

2. Add a domain to your app

c2a domain add --app myapi api.example.com

3. Add DNS records at your provider

Create 2 CNAME records at your DNS provider:

#	Type	Name	Value	Purpose
1	CNAME	api.example.com	ingress.apps.clue2.app	Routes traffic to your app
2	CNAME	_acme-challenge.api.example.com	_acme-challenge.api.example.com.apps.clue2.app	Enables automatic TLS certificate

Some registrars reject ingress.apps.clue2.app

If your registrar rejects the CNAME value, use the raw load balancer hostname instead: a4418732860c946b68cefdd6a85c0a97-1177710527.us-west-2.elb.amazonaws.com

4. Wait for activation

Once DNS propagates (seconds to minutes):

• Status changes: Waiting for DNS → Issuing certificate → Live
• Your app is accessible at https://api.example.com with a valid TLS certificate

---

Common Patterns

Multiple apps under one domain

Register a domain once, then assign different subdomains to different apps:

c2a domain register example.com --method DELEGATION
# (set up NS records at registrar, verify)

c2a domain add --app frontend www.example.com
c2a domain add --app backend api.example.com
c2a domain add --app docs help.example.com

Multiple domains per app

Assign multiple domains to the same app:

c2a domain add --app myapp api.example.com www.example.com admin.example.com

Subdomain zone (e.g., app.example.com)

If you don't want to delegate your entire domain, register a subdomain zone instead:

c2a domain register app.example.com --method DELEGATION

Then at your registrar, add NS records for app.example.com (not the root domain). This leaves your existing DNS intact while delegating only the app. subdomain.

c2a domain add --app frontend web.app.example.com
c2a domain add --app backend api.app.example.com

---

CLI Reference

c2a domain register

Register a custom domain for your project.

c2a domain register <domain> [--method DELEGATION|CNAME_ONLY] [--project <name>]

Option	Default	Description
--method	CNAME_ONLY	DELEGATION for automatic DNS, CNAME_ONLY for manual
--project	active project	Project to register the domain under

c2a domain add

Add one or more custom domains to an app. Auto-registers the base domain if needed.

c2a domain add --app <app-name> <fqdn> [<fqdn>...] [--method DELEGATION|CNAME_ONLY] [--no-wait]

Option	Description
--app, -a	App name to assign domain(s) to (required)
--method, -m	DNS method for auto-registration if domain isn't registered yet
--no-wait	Skip polling for status
--project, -p	Project name

c2a domain info

Show domain details and reprint NS record setup instructions.

c2a domain info <domain>

c2a domain verify

Verify NS records are correctly configured for a DELEGATION domain. Performs a live DNS lookup.

c2a domain verify <domain>

c2a domain list

List all domains (platform + project custom domains).

c2a domain list [--project <name>] [--format table|json]

c2a domain assignments

List domain assignments for the current project.

c2a domain assignments [--app <name>] [--project <name>] [--format table|json]

c2a domain status

Check DNS delegation status for a domain (via API).

c2a domain status <domain>

c2a domain unassign

Remove a domain assignment from an app.

c2a domain unassign <fqdn> [--yes]

c2a domain delete

Delete a registered custom domain and all its assignments.

c2a domain delete <domain> [--yes]

---

MCP Tools

If you're using Clue2App via Claude Code or another MCP client, these tools are available:

Tool	Description
c2a_domains_register	Register a domain zone (DELEGATION or CNAME_ONLY)
c2a_domains_add	Add custom domain(s) to an app
c2a_domains_info	Show domain details and NS instructions
c2a_domains_verify	Verify NS records for a DELEGATION domain
c2a_domains_list	List domains in the project
c2a_domains_remove	Remove a domain assignment
c2a_domains_delete	Delete a registered domain

---

Console UI

Adding a domain

1. Open your app in the console
2. Go to the Domains tab
3. Click Add Domain
4. Select a registered domain from the dropdown (or register a new one)
5. Enter the subdomain name
6. Click Add

For DELEGATION domains, the status will show "Issuing cert..." and go live automatically in ~90 seconds.

For CNAME_ONLY domains, the status will show "Waiting for DNS" — follow the CNAME instructions shown.

Domain status indicators

Status	DELEGATION	CNAME_ONLY
Pending	Issuing cert...	Waiting for DNS
DNS Verified	Issuing cert...	Issuing cert...
Active	Live	Live
Failed	Check logs	Check DNS records

---

DNS Provider Guides

Cloudflare

1. Go to your domain's DNS settings in the Cloudflare dashboard
2. Click Add record
3. For each CNAME record:
   • Type: CNAME
   • Name: the subdomain (e.g., api) or full name for the challenge record
   • Target: the value from the table above
   • Proxy status: DNS only (gray cloud) — do NOT proxy through Cloudflare
4. Click Save

Cloudflare Proxy

Set the proxy status to DNS only (gray cloud icon). If the orange cloud (proxied) is enabled, TLS certificate issuance will fail because Cloudflare intercepts the ACME challenge.

GoDaddy

1. Go to My Products → select your domain → DNS
2. Click Add under DNS Records
3. For each CNAME:
   • Type: CNAME
   • Name: the subdomain part only (e.g., api, _acme-challenge.api)
   • Value: the target value
   • TTL: 1 Hour (or lower)
4. Click Save

Squarespace (Google Domains)

1. Go to DNS settings for your domain
2. Under Custom records, click Manage custom records
3. For each CNAME:
   • Host name: the subdomain (e.g., api)
   • Type: CNAME
   • Data: the target value
   • TTL: 3600
4. Click Save

Squarespace CNAME limitation

Squarespace may reject ingress.apps.clue2.app as CNAME data. Use the raw ELB hostname instead (shown in the CLI output).

---

Troubleshooting

Domain stuck on "Waiting for DNS" (CNAME_ONLY)

• Verify both CNAME records are set correctly at your DNS provider
• DNS propagation can take up to a few hours depending on TTL settings
• If using Cloudflare, ensure proxy is disabled (gray cloud)
• Run dig api.example.com CNAME to verify the record resolves

Domain stuck on "Issuing certificate"

• For CNAME_ONLY: verify the _acme-challenge CNAME is set correctly

  dig _acme-challenge.api.example.com CNAME

• For DELEGATION: verify NS records are propagated

  c2a domain verify example.com

• Certificate issuance typically takes 60–90 seconds after DNS is verified

NS records not propagating (DELEGATION)

• Run c2a domain verify <domain> to check
• Verify you replaced (not just added) the nameservers at your registrar
• Some registrars take up to 48 hours, but most propagate within 30 minutes
• Try checking from a public resolver: dig NS example.com @8.8.8.8

Domain shows "Failed"

• The system timed out waiting for DNS or certificate
• Check and fix your DNS records, then remove and re-add the domain

Reprint NS records

If you need to see the NS records again after registration:

c2a domain info example.com

Limitations

• Apex domains (e.g., example.com without www): Supported with DELEGATION mode only
• Wildcard certs: Only available with DELEGATION mode
• Let's Encrypt rate limits: 50 certificates per registered domain per week
• DNS propagation: Depends on your DNS provider and TTL settings
• DELEGATION nameserver change: Transfers DNS control — existing records must be recreated in Route53