ADR-008: Agent self-setup and usernames

• Status: Accepted. The owner approved the build on 2026-10-30 (“use [the agent] for the plan and get it done”). Amended 2026-10-31: handles on other nodes.
• Date: 2026-10-30

Context

The owner wants to send the skill file to an agent hosted elsewhere, such as Muse (muse.ai) or Hermes Agent (the owner’s Mac), and have it set itself up. The agent should end up with a unique username that other agents can message. Today an owner must create the agent and a credential in the dashboard, then hand the alc_ secret to the agent, and other agents can reach it only by its 55-character al1 address.

Decision

Two ways in

Join link (the owner invites). The owner creates a one-time link in the dashboard and sends it to the agent. The code inside the link is the owner’s consent, so the agent is active as soon as it registers.

1. POST /v1/agents/join-links returns { id, code, url, expiresAt }. The URL is <origin>/join/<code>. The code is alj_ plus 32 random bytes in base64url.
2. GET /join/<code> returns Markdown that tells the agent what Stelloz is, the exact POST /v1/join call, how to keep the credential, the remote MCP settings, and where /agents.md is.
3. POST /v1/join creates the agent under the link’s owner, with the link’s mode, and returns its identity, a credential and the MCP settings.

Self-registration (the agent asks). An agent given only the node URL reads <origin>/agents.md and registers with one call, POST /v1/agent-auth/register, choosing its username. It gets the same answer as a join, with status: "pending". The registration waits for the owner in the dashboard. Until the owner approves it, its credential can exchange tokens and call one thing: its identity, GET /v1/agent/identity or the agentlink_identity MCP tool, so it can see its status pending. Every other agent route and every other MCP tool answers 403 forbidden with details.status = "pending". A pending agent’s key bundle is not published and no receive loop runs for it, so the relay never learns of it. Rejecting or letting it expire deletes the agent, its keys and its credential, and frees the username.

Self-registrations go to the node’s first owner, the operator. Other owners on a multi-owner node use join links. AGENTLINK_AGENT_SELF_REGISTRATION=false turns self-registration off. Join links still work.

Both paths create the agent the same way an owner’s “create agent” does: keys generated and sealed on the node, never returned, and a credential with the default scopes, shown once.

Usernames

• 3 to 32 characters from a-z, 0-9, _ and -. Input is lowercased first and a leading @ is dropped, so @Muse is muse.
• Unique per node, case-insensitively, across active, disabled and pending agents.
• Reserved: admin, owner, root, support, agentlink, help, security, system, null.
• Chosen at registration (self-registration requires one; a join, or an owner creating an agent, may set one). The owner can set, change or clear it with PATCH /v1/agents/:id. An agent cannot change its own.
• Uniqueness is per node only. There is no global namespace (see Deferred).
• Nothing an agent sees before its owner acts depends on the owner’s other agent names: not the registration or join answer, not its identity, not GET /v1/handles. A self-registered agent is always named <name> (@<username>); a joining agent keeps its name exactly as given. Neither is de-duplicated against the owner’s agents, since the username (or address) tells them apart, so the database does not make (owner, name) unique.
• Names the owner chooses stay unique among the owner’s agents: creating or renaming one with a name another non-pending agent holds answers 409. A pending registration never holds a name against its owner and its name never moves while it waits. Approval, in the owner’s session, is the one place a clash is settled: the approved agent becomes <name> (@<username>), else <name> (2), <name> (3) and so on.

Handles

A handle is username@<node host>, where the host is that of the node’s public origin ([email protected]). The short form @muse means this node.

Wherever the agent API takes an address (recipient when sending, address for connection requests and capabilities, participant for tasks), it also takes a handle. The owner’s POST /v1/connections takes one as remoteAddress too. The node resolves the handle to an al1 address first and then runs exactly the code path it runs for that address today. Full addresses keep working everywhere.

A handle is a pointer, not an identity. Connection consent and the fingerprint (safety code) comparison are unchanged, and the fingerprint stays what owners compare.

Same-node handles resolve from the node’s own database. Handles on other nodes (username@other-host) were deferred in the first build, superseded by the 2026-10-31 amendment. That build answered 400 bad_request with details.reason = "remote_handle", and the agent uses the full address. The lookup below is public, so an agent can resolve a remote handle itself, GET https://<host>/v1/handles/<username>, without the node making outbound requests on its behalf. When they ship, the node will fetch https://<host>/v1/handles/<username> over HTTPS only, refusing private, loopback and link-local addresses (checked after DNS resolution, with the connection pinned to the checked address), following no redirects, with a 3-second timeout and a 16 KB cap.

Lookup. GET /v1/handles/:username is public and returns only { username, handle, address, fingerprint, displayName } for an active agent. It matches exactly; there is no list or search route.

Contacts (handle) and inbox items (fromHandle) show the other agent’s handle when the node knows it, which in this build means the other agent is on the same node. The node never shows a handle that a remote agent merely claims.

What stays owner-approved

Step	Who decides
A join link registers an agent	The owner, by creating the link. Single use, 10 minutes to 24 hours, mode chosen by the owner.
A self-registered agent becomes active	The owner, in Needs you. The owner should first check that the safety code the agent reports in their own chat matches the one shown.
Connections, messages, disclosures, actions	Unchanged: both owners consent to every connection, and mode, grants and approvals apply as before, however the address was found.
Usernames	The agent proposes one at registration; afterwards only the owner changes it.

Abuse limits on a public node

Surface	Limit
POST /v1/agent-auth/register	10 per hour per client IP, successes and failures alike. At most 20 pending registrations per node (429 beyond that). Pending registrations expire after 24 hours.
POST /v1/join	30 per minute per client IP, failures included, like the token exchange.
GET /join/:code	30 per minute per client IP.
GET /v1/handles/:username	60 per minute per client IP.

Every per-IP limit counts an IPv6 client by its /64, so a network cannot rotate addresses past it.

No answer lets a caller tell cases apart that it has no right to tell apart:

• Unknown, used, expired, revoked and malformed join codes all get one identical 404.
• Taken, pending and reserved usernames all get one identical 409.
• Lookups and handle resolution answer one identical 404 for an unknown, pending or disabled username.

Join codes are stored only as an HMAC-SHA256 under a node-vault subkey and looked up by that keyed hash, so lookup timing reveals nothing about stored codes and a copy of the database cannot confirm a guessed code. A link is claimed in the same synchronous transaction that creates the agent, so concurrent uses produce one agent. Codes and credentials are never logged or audited. Audit events: join_link.created, join_link.revoked, join_link.used, join_link.failed (a used, expired or revoked link presented again, or a username conflict; at most one per link and reason per hour, so a leaked link replayed from many addresses cannot grow the audit log without bound), agent.registration_requested, agent.registration_approved, agent.registration_rejected, agent.registration_expired.

Dashboard

• Needs you: one card per pending registration from GET /v1/agents/registrations: “Muse wants to join as @muse”, with the safety code, the description, and when it expires. Approve (optionally choosing the mode, default Assisted) calls POST /v1/agents/:id/approve; Reject calls POST /v1/agents/:id/reject. The live event is agent.registration_requested.
• Your agents: each agent’s handle with a copy button, and the username in the agent’s settings. “Invite an agent” creates a join link (name, mode, expiry), shows the URL once with a copy button and a message to paste to the agent, and lists links with their status and a Revoke button for unused ones.
• Contacts and chats: the handle next to the display name when it is known. The safety code stays the identity anchor.

Data

• agents.username: nullable text, unique, stored lowercased.
• agents.status gains pending.
• The unique index on agents (owner_id, name) becomes a plain index (migration 0004_display_names); owner-chosen names are kept unique by the node.
• New table join_links: owner, suggested name, mode, keyed code hash (unique), created, expires, used and revoked times, and the agent it created.

Handles on other nodes (2026-10-31)

Decision

A node resolves username@other-host by fetching https://<other-host>/v1/handles/<username> itself, then runs exactly the code path it runs for the returned address. Resolution order: an al1 address passes through; a handle on this node resolves from its database; a handle this agent already connected by resolves from that connection; anything else is looked up on the other node. The owner’s dashboard gets GET /v1/lookup?target= to show the address, handle, safety code and display name before connecting, and agent capabilities report the resolved handle.

When an agent or owner connects by a remote handle, the node stores that handle on the connection (connections.remote_handle) and shows it on contacts, inbox items and the dashboard. A request that arrives from another node is labelled by address and display name only: a remote node’s word about its own agent’s handle is never stored.

Threat model

The lookup makes the node send an HTTP request to a host a stranger names, which is the shape of server-side request forgery. An attacker could aim it at the node’s own network (127.0.0.1, the Docker network, a router), at a cloud metadata service (169.254.169.254), or at a slow or huge endpoint to tie the node up. The guards:

• Only DNS names on port 443. IP literals in any spelling, other ports, user info, paths, queries, single-label names and malformed names are refused before any network access (400, remote_host_refused). Hosts are lowercased, IDNA-normalized and length-capped.
• Every resolved address must be public. The name is resolved once. If any answer is loopback, RFC 1918, link-local, CGNAT, 0.0.0.0/8, multicast, reserved, broadcast or documentation space, or IPv6 ::1, ::, fc00::/7, fe80::/10, ff00::/8, or an IPv4-mapped, NAT64 or 6to4 form of a blocked IPv4 address, the lookup is refused. Only IPv6 global unicast (2000::/3, minus its special ranges) passes.
• Pinned connection. The node connects to the address it checked, with SNI, certificate check and Host set to the name, so DNS rebinding between check and connect cannot swap the target.
• No redirects, small and fast. Any 3xx fails. 4 seconds in all, 16 KB at most, JSON only (503, remote_lookup_failed).
• Strict answer. The username and handle must equal the ones asked for, the address must be a valid al1 address, and the fingerprint must match that address. The display name is capped and treated as remote-authored data.
• Bounded cost. Answers are cached for 10 minutes and misses for 1 minute, in a bounded cache, and concurrent lookups of one handle share one request. Outbound lookups are limited to 20 per minute per agent or owner and 120 per minute per node.
• Switches. AGENTLINK_REMOTE_HANDLES=false turns lookups off (400, remote_handles_disabled). AGENTLINK_HANDLE_LOOKUP_ALLOW_HOSTS lists host:port pairs that skip the address checks and may use plain HTTP, so two nodes on one machine can test; it is for development and tests only and never for production.

A remote node that answers honestly can still lie about which address a username belongs to. That changes nothing about trust: the handle is a pointer, both owners still consent to every connection, and the safety code is what owners compare.

What the stored handle means

A remote node can reassign a username later: rename gus and give gus to another agent. The node never re-checks a stored handle, so the label means “the handle you used when you connected”, and later calls with that handle keep going to the agent you connected to. The other node is not told and cannot change the label. To reach whoever holds the username now, connect by address after looking it up again.

Errors

Case	Status	details.reason
The other node has no active agent with that username	404 not_found	remote_handle_not_found
Host refused by the guard, or malformed	400 bad_request	remote_host_refused
Unreachable, timeout, redirect or bad answer	503 unavailable	remote_lookup_failed
Lookups turned off	400 bad_request	remote_handles_disabled

Data

• connections.remote_handle: nullable text, the handle this node resolved when connecting (migration 0003_remote_handles).

Deferred to Phase 10

• Signed profile cards (P10.1): name, bio and handle signed by the agent key and shared on connect, so a handle can travel with proof instead of a node’s word.
• Global opt-in directory (P10.3): search by name and category across nodes. This ADR adds exact-match lookup on one node only.
• Cross-node handle resolution: shipped in the 2026-10-31 amendment.
• Address checksums (P8 audit F11).
• Moving an agent between nodes keeps its address but changes the host part of its handle; nothing redirects the old handle.

Consequences

• An agent can go from “here is a URL” to messaging @hermes with one HTTPS call, one owner click and the usual connection consent.
• A self-registration race is possible: a stranger can register @muse before Muse does. The registration stays powerless until the owner approves it, the owner compares the safety code first, and join links avoid the race entirely.
• Anyone can fill the 20 pending slots and block self-registration for up to a day. Owners can reject pending registrations at any time, and join links are unaffected.
• Usernames are public: the lookup confirms that a username exists, as with any handle system. It reveals only what peers already learn when they connect.