Content
<div align="center">
# `a-i.st`
### Give your AI agent an address.
> Live at **[a-i.st](https://a-i.st)** · `a-i.sh` 301s here · repo stays `kwkuh/a-i.sh`
> (the star-gate target). Two free suffixes: `name.a-i.st` and `name.a-i.sh`.
**Free subdomains for AI agents, bots & assistants.**
GitHub-verified · public registry · forever free · powered by Cloudflare's edge.
[**🚀 Claim yours →**](https://a-i.st) · [**📖 Registry →**](https://a-i.st/directory) · [**⭐ Star this repo**](https://github.com/kwkuh/a-i.sh)
<br>
</div>
---
```sh
~ $ curl https://youragent.a-i.st/health
{ "agent": "youragent", "status": "alive" }
~ $ dig +short youragent.a-i.st
→ resolves via Cloudflare anycast — 250+ PoPs, ~1ms worldwide
```
Your agent runs *somewhere*. What it often doesn't have is **a clean,
memorable address** anyone can reach it at.
`a-i.st` gives it one. Pick a name, point it wherever your agent lives,
ship in about 30 seconds. No credit card, no DNS console.
---
## Why this exists
Every agent now benefits from a **stable public identity**: an MCP
endpoint, a webhook receiver, an OAuth callback, an A2A discovery URL.
Standing up that identity normally means a registrar, nameservers, DNS
records, and SSL before you've written a line of agent code.
> **`a-i.st` is a free identity layer for the agent era.** One name.
> One click. Public registry so agents are *discoverable*, not just
> *addressable*.
## How it works
```
┌─────────────┐ GitHub OAuth ┌──────────────┐ verify ┌───────────┐
│ You + an │ ───────────────► │ a-i.st │ ──────────► │ GitHub │
│ AI agent │ │ (Worker) │ ◄────────── │ API │
└─────────────┘ └──────┬───────┘ └───────────┘
│ Cloudflare DNS API
▼
youragent.a-i.st → your runtime
(anycast, 250+ PoPs, instant)
```
1. **Sign in** with GitHub — ownership verified, no impersonation, no squatting.
2. **Follow along on GitHub** — follow [`@kwkuh`](https://github.com/kwkuh)
and star the repo if you'd like to support the project. It helps keep
a-i.st free for everyone.
3. **Claim** `name.a-i.st` (or `name.a-i.sh`), point a CNAME/A/AAAA/TXT
wherever your agent runs. Live instantly. Listed in the public
registry, queryable via RDAP/WHOIS.
3 free subdomains per account. GitHub account must be ≥30 days old.
1 claim / 24h. Reserved & impersonation names blocked. Every action audited.
## What you can point to
| Record | Use it for |
|--------|------------|
| `CNAME` | Any platform that gives you a hostname |
| `A` / `AAAA` | A server or box you run yourself |
| `TXT` | Verification, agent metadata, A2A discovery records |
## Self-host it
The whole thing is one Worker + one D1 database + a Next.js frontend.
It runs inside Cloudflare's free tier — unlimited DNS records, 100k Worker
requests/day. Your operating cost is the domain and nothing else.
```bash
git clone https://github.com/kwkuh/a-i.sh && cd a-i.sh/api
npm i
npx wrangler d1 create aish-db # → paste id into wrangler.toml
npx wrangler kv namespace create SESSIONS # → paste id into wrangler.toml
npm run db:init:remote # load schema
npx wrangler secret put GH_OAUTH_CLIENT_SECRET
npx wrangler secret put CF_API_TOKEN # DNS:Edit on the a-i.sh zone
npx wrangler secret put CF_ZONE_AISH
npx wrangler secret put SESSION_SECRET # random 32+ chars
npm run deploy # → api.a-i.sh
# frontend (Next.js static export)
cd ../web-next && npm i && npx next build
npx wrangler pages deploy out --project-name=aish
```
Full walkthrough: [`README` setup section](#) · local dev with `DEV_MODE=1`
mocks OAuth and skips real DNS so you can test the whole flow offline.
### Local dev in 10 seconds
```bash
cd api
echo "DEV_MODE=1" > .dev.vars # + dummy secrets, see README
npx wrangler d1 execute aish-db --local --file=./schema.sql
npx wrangler dev --local
# open /auth/dev-login?login=you&follow=1&star=1 → full flow, no GitHub
```
## Architecture
```
web-next/ Next.js (App Router, static export) → Cloudflare Pages
├── src/app/ landing · dashboard · directory · whois · check · admin
├── src/components/ Nav · Footer
└── src/lib/api.ts typed API client (graceful offline degradation)
api/ Hono on Cloudflare Workers
├── src/index.ts OAuth · gate · claim · DNS · RDAP · WHOIS · admin
├── schema.sql D1: users · subdomains · audit_log · reserved
└── wrangler.toml bindings & config
```
Next.js static export — zero server cost, ships only static assets + a
~105 kB JS bundle to the edge. The Worker is ~29 kB gzipped.
## Registry tooling
| Endpoint | What |
|----------|------|
| `GET /rdap/domain/{fqdn}` | RFC 9083 RDAP (privacy-redacted registrant) |
| `GET /rdap/entity/{handle}`, `/rdap/help` | RDAP entity + help |
| `GET /whois?domain={fqdn}` | Classic WHOIS (text/plain) |
| `POST /api/check/bulk` | Bulk availability + name suggestions |
| `/admin` | Console: stats, registrations, users, audit, reserved |
## Roadmap
- [x] GitHub OAuth + follow/star gate
- [x] Claim / manage / release · public registry · audit log
- [x] RDAP (RFC 9083) + WHOIS + bulk checker + admin console
- [x] Next.js frontend
- [ ] Wildcard records (`*.myagent.a-i.sh`)
- [ ] CLI — `npx a-i-st claim <name> --to <your-host>`
- [ ] A2A discovery — `/.well-known/agent.json` auto-served
- [ ] Programmatic API for agent frameworks
## Star history
Stars are literally the gate — and they draw the curve. Thanks for being on it.
[](https://www.star-history.com/#kwkuh/a-i.sh&Date)
## Contributing
Issues and PRs welcome — see [`CONTRIBUTING.md`](./CONTRIBUTING.md).
The reserved/blocklist in [`api/schema.sql`](./api/schema.sql) is the one place
PRs get the most scrutiny: we never want a name that enables impersonation.
## License
[MIT](./LICENSE) © [Kukuh Laksana](https://github.com/kwkuh) — an
[OpenClaw](https://github.com/kwkuh) project.
<div align="center"><br><sub>
Built for the agents. Give yours a shell → **[a-i.sh](https://a-i.sh)**
</sub></div>
