Agentdomains

AgentDomains — free domains for the sites agents build

AgentDomains hands out real, public domains from a single CLI command. Names live under two domains: makes.fyi (the default) and agentdomains.co, so you can claim yourname.makes.fyi or yourname.agentdomains.co. No web forms. Signing up needs nothing at all; the account's first name needs an email address, used only for the confirmation link. Full docs: https://docs.agentdomains.co

When to use this skill

Reach for AgentDomains when you need a public hostname and don't have one:

• exposing a local/dev server to the internet,
• a stable URL for a webhook or callback,
• hosting a small site or API for an agent,
• giving a long-running agent a memorable address.

If the user already has a domain they control, prefer that. AgentDomains is for the "I just need a hostname, fast and free" case.

Setup (once)

Ensure the CLI is installed, then create an account. The bundled helper does both:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh"

Or manually:

go install github.com/tashfeenahmed/AgentDomains/cmd/agentdomains@latest
agentdomains signup            # saves an API key to ~/.agentdomains/config.json

signup creates an anonymous provisional account and asks for nothing — no email, no form. One account can hold up to ten names at once. The first time you register a name you must pass --email, or the API answers 400 registering a name needs an email: we send a confirmation link and start a 30-day clock. A human confirms the link to make the account (and all its names) permanent — otherwise the account and every name on it are deleted automatically after 30 days.

agentdomains email you@example.com   # (re)send the confirmation link any time

Core workflow

Always pass --json so you can parse results reliably.

# register a name and point it at an IP in one step (first claim needs --email)
agentdomains claim mybot --email you@example.com --type A --content 203.0.113.10 --json
# -> response includes a "note": tell the user to confirm within 30 days or it's deleted

# after the first claim the email is remembered on the account, so it's optional:
agentdomains claim mybot2 --type CNAME --content my-app.vercel.app --json

# claim under agentdomains.co instead of the default makes.fyi
agentdomains claim mybot --domain agentdomains.co --type A --content 203.0.113.10 --json

# inspect / manage (add --domain to scope when a label exists under both)
agentdomains list --json
agentdomains get mybot --json
agentdomains record mybot --type A --content 203.0.113.10 --host www --json
agentdomains unrecord mybot <record-id> --json   # drop ONE record, keep the name
agentdomains delete mybot --json

Names are claimed under makes.fyi by default; pass --domain agentdomains.co to use the other one. Parse the fqdn field from claim/get to learn the live hostname, e.g. mybot.makes.fyi.

Getting HTTPS

AgentDomains handles DNS, so you bring your own certificate:

• HTTP-01 (simplest): point the domain at your server, then certbot certonly --standalone -d mybot.makes.fyi.
• DNS-01 (no inbound server): add the challenge token as TXT: agentdomains txt mybot "<token>" --host _acme-challenge --json.

Forwarding (URL redirect)

Send a name to any URL with a real HTTP redirect, served at Cloudflare's edge with valid HTTPS. forward claims the label first if you don't own it, so it's one step:

agentdomains forward mysite https://destination.example.com --json
# mysite.makes.fyi -> 302 redirect to https://destination.example.com

# 301 permanent instead of the default 302 temporary:
agentdomains forward mysite https://dest.com --permanent --json

# always land on the target root (don't carry the request path/query):
agentdomains forward mysite https://dest.com --no-preserve-path --json

# remove a forward (keeps the label):
agentdomains unforward mysite --json

Path and query are preserved by default.

A forward takes the hostname over. Any A/AAAA/CNAME sitting on the label itself is deleted as part of the call and listed back in replaced_records, so you never have to clear the way first — claiming with a record and then forwarding is a perfectly good sequence. Records on a sub-label (www.mysite.makes.fyi) are different hostnames and survive, and TXT records are left alone. Going the other way is still refused: while a forward is in place, adding an address record to the same label answers a 409 telling you to unforward first.

Reverse proxy (serve a backend at the name)

Serve a backend you run elsewhere at the name, over HTTPS, with our edge certificate — nothing to set up on the backend, and the name stays in the address bar (unlike a forward, which redirects away). proxy claims the label first if you don't own it:

agentdomains proxy shop myapp.fly.dev --json
# shop.makes.fyi serves https://myapp.fly.dev over our cert, at shop.makes.fyi

# remove the proxy (keeps the label):
agentdomains unproxy shop --json

We terminate HTTPS at the edge and fetch the backend by its own hostname, so it accepts the request without a certificate for the AgentDomains name. Like a forward, a proxy replaces the label's own A/AAAA/CNAME records and reports them as replaced_records; a proxy and a forward remain mutually exclusive, so unforward before proxying a forwarded label.

Caveat: the proxy serves the backend but can't rewrite hostnames the app hardcodes. Apps that bake their own domain into OAuth/SSO redirects (e.g. a Keycloak login) may bounce users to the backend's native hostname mid-login until the AgentDomains name is added in the app's own settings. Static sites and apps using relative URLs work with no setup.

Nameserver delegation

To control the whole subtree yourself:

agentdomains ns mybot ns1.yourdns.com ns2.yourdns.com --json

Non-interactive / sandboxed use

The CLI reads credentials from the environment, so no interactive setup is needed:

export AGENTDOMAINS_API_KEY=adom_...      # reuse an existing key
export AGENTDOMAINS_API_URL=https://api.agentdomains.co

You can also call the HTTP API directly; see https://docs.agentdomains.co#api.

Prefer MCP?

Everything above is also available as typed MCP tools, if your client speaks MCP and you would rather not shell out. Seventeen tools covering the same operations: availability, signup, claiming, records, ACME challenges, forwarding, proxying, delegation, and closing the account.

• Hosted: https://mcp.agentdomains.co (Streamable HTTP). Nothing to install. claude mcp add --transport http agentdomains https://mcp.agentdomains.co --header "Authorization: Bearer adom_…"
• Local: npx -y agentdomains-mcp (npm package agentdomains-mcp, stdio), reading AGENTDOMAINS_API_KEY or falling back to the CLI's ~/.agentdomains/config.json.

The same adom_… API key works for the CLI, the MCP server, and the HTTP API — there is nothing separate to provision. Pick whichever interface fits; they are not alternatives to choose between permanently. Reference: https://docs.agentdomains.co/#mcp

Notes

• Names: lowercase letters, digits, hyphens; some labels (e.g. api, www) are reserved.
• Labels are lowercased when claimed: asking for MyApp gives you myapp.makes.fyi, and that lowercase label is what every later command (get, record, delete) expects.
• Undoing one record: agentdomains unrecord <label> <record-id> --json removes a single record and keeps the name. Record ids come from get (and from the claim / record responses).
• A claim and its first record stand or fall together. If the record is malformed (400) or the DNS provider refuses it (503), the label is not claimed — retry the whole claim once you have fixed the record. Re-claiming a name you already hold is not a failure: the CLI prints "you already own …" and exits 0, and the API answers 409 {"owned":true}.
• Closing an account: agentdomains account delete --json deletes the account and invalidates its API key. It refuses while names are still held and lists them; add --force to delete those names along with it. There is no undo — the names go back into the pool for anyone to claim.
• Errors say whether to retry. An upstream failure answers 503 with retry:true (an outage — come back in a moment) or retry:false (a misconfiguration on our side; retrying is pointless, report it instead).
• Cost: none. There is no paid tier, no card, and no quota to top up — the only limit is ten names per account. Nothing here will ever ask the user to pay.
• Be a good citizen: claim what you need, delete what you don't.
• Service & docs: https://agentdomains.co · https://docs.agentdomains.co