Existing `.loc.cc` Domain Recovery and Tunnel Routing

Diagnostic order

Authenticate to the account that owns the domain.
GET /api/domains and locate the exact full_domain.
Record id, status, suspend_reason, first_failed_at, dns_synced, and scan_summary.
GET /api/domain-scans/{id} to distinguish DNS, HTTP, and TLS failures.
GET /api/dns/{id}/records; check synced_to_powerdns and sync_error per record.
If provider state may be stale, POST /api/dns/{id}/records/sync-from-powerdns.
Query ns1.nodelook.com and ns2.nodelook.com directly, then public resolvers.
Test public HTTP/TLS and application endpoints from outside the origin network.

Important failure signatures

Domain resolves but remains suspended

Typical fields:

{
  "status": "suspended",
  "suspend_reason": "Domain down for 7 days",
  "scan_summary": {
    "dns_status": "resolved",
    "http_status": "offline",
    "ssl_status": "invalid"
  }
}

This is not a registration failure. Restore externally reachable HTTP/TLS and wait for/trigger only a documented health scan. Do not invent an unsuspend endpoint.

Cloudflare Tunnel error 1001

Symptoms:

tunnel connector is healthy;
hostname exists in local ingress;
DNS CNAME points to <uuid>.cfargotunnel.com;
HTTP via Cloudflare returns error code: 1001 or TLS cannot be provisioned.

Interpretation: the hostname was not routed from a Cloudflare-managed zone/account. A raw external CNAME is insufficient. Confirm the parent zone is available through /zones and that cloudflared tunnel route dns or the equivalent API route succeeds before relying on this design.

DNS record safety

Apex CNAME/ALIAS commonly conflicts with MX and TXT records.
Preserve mail and domain-verification records unless the user explicitly accepts losing them.
A dedicated api hostname avoids apex coexistence conflicts but not Cloudflare ownership constraints.
After mutation, verify both API state and authoritative DNS. A successful POST alone is not completion.

Static ngrok fallback discovered from local state

When a vanity domain cannot be published, search account inventories and prior sessions for an assigned static ngrok hostname before settling for a random ngrok-free.app URL.

Credential distinction:

agent authtoken is enough to start a tunnel on a static hostname already assigned to that account;
an ngrok api_key is only needed for management commands such as reserved-domain listing/creation.

Operational ownership test:

ngrok http --domain=<assigned-hostname> 8080 --authtoken <authtoken>

Require the log to show started tunnel with the exact hostname, then test the public routes. Persist the exact command in startup automation and update all URL consumers. Do not describe this fallback as the vanity domain itself.

Completion gate

Report a stable domain only when all are true:

authoritative and public DNS agree, or the static tunnel agent confirms the exact assigned hostname;
TLS certificate is valid for the hostname;
/health returns 200 externally;
/v1/models or the product's real API route returns the expected authenticated/public response;
bot/docs/config/tests references use the same verified hostname;
the affected application was restarted and its live URL configuration read back;
a restart/autostart path for the tunnel or reverse proxy is present and tested.

3.4 KiB Raw Permalink Blame History

Existing .loc.cc Domain Recovery and Tunnel Routing