@agentcommunity/dmv-agent

Pre-register .agent identities at the Department of Machine Verification.

Part of the .agent community — building toward an ICANN application for the .agent gTLD.

Three registration paths

| Path | Who | Type | Where | |------|-----|------|-------| | CRT Terminal (web) | Humans & organizations | Individual or Organization | dmv.agentcommunity.org | | CLI (this package) | AI agents | Agent (operator required) | Your terminal | | MCP server | Autonomous agents | Agent (via Claude Code) | Claude Code / any MCP client |

All paths hit the same backend. Pre-registration records interest in a .agent domain — it does not guarantee assignment.

Quick start

CLI (for agents)

# Interactive CRT terminal experience
npx @agentcommunity/dmv-agent register

# Non-interactive (for scripting / agentic workflows)
npx @agentcommunity/dmv-agent register \
  --name my-agent \
  --email [email protected] \
  --operator "Acme Labs"

# Verify a certificate ID (offline, no network)
npx @agentcommunity/dmv-agent verify MESA-DD6-660J

The interactive CLI mirrors the web CRT terminal — ASCII art frame, green terminal colors, step-by-step form with validation, about/terms/charter access, and a confirmation gate before submit.

Claude Code skill

Copy the skill into your project:

mkdir -p .claude/skills
cp -r node_modules/@agentcommunity/dmv-agent/skills/dmv .claude/skills/

Then type /dmv in Claude Code to start pre-registration.

MCP server (for autonomous agents)

Add to your Claude Code settings (.claude/settings.json):

{
  "mcpServers": {
    "dmv": {
      "command": "npx",
      "args": ["@agentcommunity/dmv-agent"]
    }
  }
}

Exposes two tools:

| Tool | Description | |------|-------------| | register_agent | Pre-register an .agent identity (agent_name, email, operator_name, description?) | | verify_certificate | Check a certificate ID's Luhn mod-36 check digit |

Badges

After pre-registration, embed a badge in your project. Badges verify live against the DMV database and link back to your certificate.

Flat badge (for READMEs)

[![my-agent.agent](https://dmv.agentcommunity.org/badge?id=MESA-DD6-660J)](https://dmv.agentcommunity.org/c/MESA-DD6-660J/my-agent)

Renders a shields.io-style SVG:

• Green: registered and verified
• Yellow-green: valid but unverified
• Red: invalid certificate ID

Card badge (for websites)

<a href="https://dmv.agentcommunity.org/c/MESA-DD6-660J/my-agent">
  <img src="https://dmv.agentcommunity.org/badge?id=MESA-DD6-660J&style=card"
       alt="my-agent.agent — DMV Certificate" />
</a>

Renders a branded 280x72 SVG with dark gradient, agent name, certificate ID, and status.

Badge URL format

https://dmv.agentcommunity.org/badge?id=CERT-ID           # flat (default)
https://dmv.agentcommunity.org/badge?id=CERT-ID&style=card # card

Badges are cached for 5 minutes. Lookup is by certificate ID only.

How it works

Pre-registration flow

Client (your machine)              Server (Supabase Edge Function)
─────────────────────              ────────────────────────────────
rate limit check (local)
validate input locally
        │
        ├── POST /register-agent ──▶  validate again
        │   + machine_fingerprint      rate limit (email + IP + fingerprint)
        │                              generate certificate ID
        │                              insert to database
        │                              ◀── return certificate
        │
record attempt locally
display result
        │
        └── verification email sent by server trigger ──▶ operator

1. Client-side rate limiting — max 3 pre-registrations per machine per 24h. Machine fingerprint (SHA-256 of hostname + username + platform) tracked in ~/.dmv-agent/registrations.json.
2. Client-side validation — fast feedback. Agent name: 3-32 lowercase alphanumeric + hyphens. Email: basic format.
3. Server-side validation — same checks repeated at the security boundary.
4. Server-side rate limiting — max 3 per email per hour, 10 per IP per hour. Machine fingerprint also sent for server-side enforcement. Cannot be bypassed.
5. Certificate ID — content-addressed via FNV-1a hash. Format: WORD-XXX-XXXC with Luhn mod-36 check digit. Deterministic: same inputs = same ID.
6. Email verification — a verification link is sent to the operator's email. Pre-registration completes only after verification. Until then, the domain interest is recorded but not active.

Certificate ID format

MESA-DD6-660J
│     │    └─ Luhn mod-36 check digit
│     └────── 6 hex chars from FNV-1a hash
└──────────── word from 32-word dictionary

Offline verification — no network needed:

npx @agentcommunity/dmv-agent verify MESA-DD6-660J
# ✓ Certificate MESA-DD6-660J has a valid check digit.

Programmatic use

import { registerAgent, verifyCertificateId } from '@agentcommunity/dmv-agent';

const result = await registerAgent({
  agentName: 'my-agent',
  email: '[email protected]',
  operatorName: 'Acme Labs',
  description: 'A helpful research assistant',
}, 'api');

console.log(result.certificateId); // MESA-DD6-660J
console.log(result.domain);       // my-agent.agent

// Offline verification
verifyCertificateId('MESA-DD6-660J'); // true

Security

No database credentials in client code. The published package contains zero secrets.

┌─────────────────┐         ┌──────────────────────────┐         ┌───────────┐
│  Your agent /    │──stdio─▶│  dmv-agent (local)        │──https─▶│  Supabase │
│  Claude Code     │         │  no secrets, just fetch() │         │  Edge Fn  │
└─────────────────┘         └──────────────────────────┘         │  (has key)│
                                                                  └───────────┘

• Edge function proxy — all writes go through Supabase Edge Functions that hold the service role key.
• Triple-layer rate limiting — client-side (machine fingerprint, 3/24h) + server-side (email 3/hr, IP 10/hr, fingerprint).
• Pre-registration model — domain is NOT unique. Multiple parties can pre-register interest in the same name. Certificate ID IS unique (same user + agent + type = same cert).
• Email verification — pre-registration is pending until the operator clicks the verification link.
• Content-addressed IDs — deterministic hashes, not sequential. Cannot be enumerated or predicted.

API reference

POST /register-agent

{
  "agent_name": "my-agent",
  "email": "[email protected]",
  "operator_name": "Acme Labs",
  "description": "optional",
  "registration_type": "AGENT",
  "signup_source": "cli",
  "machine_fingerprint": "sha256hex..."
}

201 — success:

{
  "certificate_id": "MESA-DD6-660J",
  "agent_name": "my-agent",
  "domain": "my-agent.agent",
  "message": "Certificate MESA-DD6-660J issued...",
  "permalink_url": "https://dmv.agentcommunity.org/c/MESA-DD6-660J/my-agent",
  "badge_url": "https://dmv.agentcommunity.org/badge?id=MESA-DD6-660J"
}

409 — already registered (returns existing cert). 429 — rate limited. 400 — validation error.

GET /lookup-agent

?id=CERT-ID     → single registration object
?domain=name    → array of pre-registrations for that domain

GET /badge

?id=CERT-ID              → flat SVG (shields.io style)
?id=CERT-ID&style=card   → branded card SVG (280x72)

Development

cd packages/dmv-agent
pnpm install
pnpm build        # compile TypeScript → dist/
pnpm dev          # watch mode

# Test locally
node dist/cli.js register
node dist/cli.js verify MESA-DD6-660J

Deploying edge functions

supabase functions deploy register-agent lookup-agent badge

See DEPLOY.md for the full go-live checklist.

License

MIT