Custom domains

A custom domain is a workspace-level mirror of everything you serve on agent37.app. Register acme-agents.com once, and every URL your workspace has also answers under it: instance ab12cd34ef becomes reachable at https://ab12cd34ef.acme-agents.com with the same X-Agent37-Key and signed-URL authentication as its instance URL, preview URLs work at https://ab12cd34ef-8080.acme-agents.com, and every public port hostname serves credential-free at https://{hostname}.acme-agents.com. Your agent37.app URLs keep working unchanged; the custom domain is an addition, not a replacement. Use a dedicated domain registered for this purpose, like acme-agents.com or acme.sh, not your main website’s domain: you delegate the whole domain’s DNS to us, and we host it from then on. One wildcard TLS certificate then covers your entire fleet, whether that’s one instance or ten thousand, with nothing to provision per instance. Subdomains of an existing domain (previews.acme.com) cannot be registered. Setup is three steps: register, set the nameservers at your registrar, verify.

Register the domain

curl -X POST https://api.agent37.com/v1/domains \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "acme-agents.com" }'

import requests

r = requests.post(
    "https://api.agent37.com/v1/domains",
    headers={"Authorization": "Bearer sk_live_..."},
    json={"domain": "acme-agents.com"},
)
print(r.json()["dns"])

const res = await fetch("https://api.agent37.com/v1/domains", {
  method: "POST",
  headers: { Authorization: "Bearer sk_live_...", "Content-Type": "application/json" },
  body: JSON.stringify({ domain: "acme-agents.com" }),
});
console.log((await res.json()).dns);

{
  "domain": "acme-agents.com",
  "status": "pending",
  "dns": {
    "type": "NS",
    "name": "acme-agents.com",
    "nameservers": ["ada.ns.cloudflare.com", "rob.ns.cloudflare.com"]
  },
  "created": 1751928000
}

domain

string

The domain you registered, lowercased. What your workspace serves lives one label below it (ab12cd34ef.acme-agents.com).

status

string

pending until verification passes, then active. Only an active domain routes.

dns

object

The nameservers to set at your domain’s registrar: replace the domain’s existing nameservers with the two in dns.nameservers.

created

integer

Unix seconds when the domain was registered.

Custom domains are a top-tier feature: they unlock once your workspace’s top-ups total $500, the same tier that raises the instance limit to 50. Below it, registration returns 403 tier_limit; email vishnu@agent37.com to unlock them another way. Register the domain itself, acme-agents.com, not *.acme-agents.com: the wildcard is implied. The name must be a registrable domain you own; a subdomain of another domain returns 400 invalid_request. A domain is claimable by exactly one workspace across the platform, first come, so a name another workspace holds returns 409 domain_exists. A registration can only ever verify with control of the domain at its registrar, so squatting buys nothing; if a domain you own is already taken, email vishnu@agent37.com.

Set the nameservers

At the registrar where the domain is registered, replace its nameservers with the two from the response’s dns.nameservers. That is the whole DNS setup: no individual records to manage, we host the domain’s DNS from then on. Registrar nameserver changes usually land within minutes, occasionally hours.

Verify

Once the nameservers are set, verify:

curl

curl -X POST https://api.agent37.com/v1/domains/acme-agents.com/verify \
  -H "Authorization: Bearer sk_live_..."

response

{ "domain": "acme-agents.com", "status": "active" }

Verification checks that the delegation has landed. It is idempotent and safe to poll: call it right after changing the nameservers, and again if it still answers pending (each call also nudges the delegation re-check, so polling genuinely speeds things up). The moment the status flips to active, the domain starts routing. TLS is one wildcard certificate covering every hostname under the domain, issued automatically when the domain activates and renewed forever after. A TLS error in the first minutes after activation means the certificate has not landed yet; wait and retry. There is nothing to provision per instance, at any fleet size.

Use it

Hit the mirrored instance URL exactly as you would the agent37.app one:

curl

curl https://ab12cd34ef.acme-agents.com/v1/health \
  -H "X-Agent37-Key: sk_live_..."

response

{ "ok": true, "agent": "hermes", "healthy": true, "hermes": true }

Authentication is identical to agent37.app: instance URLs and preview URLs (ab12cd34ef-8080.acme-agents.com) take an X-Agent37-Key header or a signed URL, public-port hostnames need no credential at all. A signed URL’s token is bound to the label it was minted for, not the domain, so a token minted for the default port also opens https://ab12cd34ef.acme-agents.com/?a37_token=.... Only labels your own workspace serves resolve under your domain. Any other label answers exactly as an unknown agent37.app URL would (401 without a credential, 404 with one), so nothing another workspace runs can ever appear under your domain. Once a domain is active, instance reads expose the mirrored URLs as domain_urls, on the instance, on each public-port entry, and on minted signed URLs. Entries are ordered oldest domain first, and the dashboard’s open and copy-link actions lead with that first domain:

{
  "id": "ab12cd34ef",
  "url": "https://ab12cd34ef.agent37.app",
  "domain_urls": ["https://ab12cd34ef.acme-agents.com"],
  "public_ports": [
    {
      "port": 8644,
      "url": "https://a1b2c3d4e5f6a7b8c9d0.agent37.app",
      "domain_urls": ["https://a1b2c3d4e5f6a7b8c9d0.acme-agents.com"],
      "prefix": null,
      "created": 1751928000
    }
  ]
}

List and delete

GET /v1/domains lists the workspace’s domains as { "data": [...] }, each entry in the full shape above (including the dns block, so you can always re-read the nameservers to set). GET /v1/domains/{domain} reads one.

curl

curl -X DELETE https://api.agent37.com/v1/domains/acme-agents.com \
  -H "Authorization: Bearer sk_live_..."

response

{ "domain": "acme-agents.com", "deleted": true }

Deleting stops routing under the domain within seconds and releases its DNS hosting; your agent37.app URLs are unaffected. The delete acts once; repeating it returns 404.

Rules and limits

Top tier only. Registering a domain requires total top-ups of $500; below that, POST /v1/domains returns 403 tier_limit.
Up to 10 domains per workspace, at no charge. Registering an eleventh returns 400 invalid_request; a bad hostname or a domain under agent37.app or agent37.com (reserved) returns 400 too.
Dedicated domains only. The whole domain’s DNS is delegated to us, so it cannot carry your website, mail, or other records. Register a domain just for this.
The path /health is answered by the platform edge itself on custom domains too, just as on agent37.app, and never reaches your app.
Traffic on a custom domain is ordinary instance traffic: same billing, and a request wakes a sleeping instance the same way.
Reads, verifies, and deletes are uniform: a domain registered by another workspace returns the same 404 as one that does not exist.

Get started

Build with Agent37

Hosting API

Agent API

Reference

Register the domain

Set the nameservers

Verify

Use it

List and delete

Rules and limits

​Register the domain

​Set the nameservers

​Verify

​Use it

​List and delete

​Rules and limits

Register the domain

Set the nameservers

Verify

Use it

List and delete

Rules and limits