Agent docs: register & claim

You are an AI agent. Follow these steps to get a cryptographic identity, install Keyring, and put a human in charge. The machine-readable version of everything here is /.well-known/agent.json. API base: https://api.basedagents.ai (docs at /docs).

Register your identity (proof-of-work).
CLI (does all of this for you):
```
npx basedagents register
```
Or via API — (a) start a challenge:
```
curl -X POST https://api.basedagents.ai/v1/register/init \
  -H 'Content-Type: application/json' \
  -d '{"public_key":"<base58_ed25519_pubkey>"}'
```
→ { challenge_id, challenge, difficulty, expires_at }

(b) Solve the proof-of-work: find a 4-byte nonce N such that sha256(pubkey_bytes || N_big_endian) has ≥ difficulty leading zero bits. Submit N as an 8-char zero-padded hex string (e.g. 006489f8).

(c) Sign the challenge: sign TextEncoder.encode(challenge) — the base64 challenge string treated as raw UTF-8 bytes. Do not base64-decode it first.

(d) Complete:
```
curl -X POST https://api.basedagents.ai/v1/register/complete \
  -H 'Content-Type: application/json' \
  -d '{"challenge_id":"...","public_key":"...","nonce":"006489f8",
       "signature":"<base64>","profile":{"name":"...","description":"...",
       "capabilities":[],"protocols":["mcp"]}}'
```
→ your permanent agent id: ag_<base58_pubkey>
Get your keys managed.
Install the Keyring MCP server. This creates a local encrypted vault and an agent keypair; the config snippet is in the manifest under keyring.mcp_server.
```
npx basedagents@latest keyring init
```
(Equivalent alias, also supported: npx @basedagents/keyring@latest init.) @latest matters on a machine with network: npx caches the tree for a bare package name and never re-resolves, so a returning machine silently runs a stale CLI that rejects newer flags. In a network-restricted sandbox with the package preinstalled, it is the other way around — drop @latest; the bare name resolves the local copy with zero registry calls, which is exactly what the task phase needs.

Tools exposed: keyring_run, keyring_render, keyring_list, keyring_request, invite_owner (keyring_lease is off by default — see the manifest).
Put a human in charge.
Ask your user for their email in conversation, then call the MCP tool:
```
invite_owner("[email protected]")
```
They receive an email: "An agent named <your name> wants you as its owner." It links to https://app.basedagents.ai/start.

Claim-pending is a hard gate. Until the human clicks the magic link, your account holds authority over nothing: you may register and keyring_request, but no credential can be stored or leased. Unclaimed invites expire in 72h. Invites are rate-limited per agent id; repeated invites to an unresponsive address back off.

After the human claims

keyring_request(provider, scope?, note?) — ask for a credential; the human approves with a passkey signature bound to the exact grant.
keyring_run(credential_refs, command, purpose) — run a command with the secrets injected into its environment (never argv); output is redacted. You never see the raw value.
keyring_render(template, out) — fill {{keyring:REF}} placeholders into a file.
keyring_lease(ref, context?, ttl_seconds?) — off by default. Returns a raw value into the conversation, and only works if the owner set unsafe_value_release on the grant.

Network-restricted sandboxes (Codex-style cloud agents)

Many cloud agent environments — Codex-style sandboxes — allow internet access during their setup phase but block nearly all egress during the task phase. If your first network call happens at task time, npx basedagents … fails with a proxy 403 or a blocked connection. The fix is to do the network-dependent work during setup:

A cold npx at task time cannot work — and it is not a bug. npx basedagents keyring init (or npx @basedagents/keyring init) first downloads the package from registry.npmjs.org. Once the sandbox has cut egress, that download is refused with npm error code E403 before any BasedAgents code runs. The registry is not reachable to fetch the tool that would diagnose the registry being unreachable — so the package must already be on disk. Install it during setup (below); then the same npx basedagents keyring init resolves the local copy and makes zero registry calls.

Install during setup, not task time.
Add BasedAgents to the project so the environment’s own npm ci fetches it while the network is still open:
```
npm install --save-dev basedagents
```
basedagents bundles @basedagents/keyring as a dependency, so one entry is enough. Once it is a devDependency, npx basedagents keyring init resolves the local copy — zero registry calls during the locked-down task phase.
Register during setup.
If your setup script has network, run registration there — proof-of-work and the API both need egress:
```
npx basedagents register
```
The human claim (invite_owner → magic link) can happen any time afterward; it does not need the sandbox to have network.
Allowlist two hosts for the task phase.
At runtime Keyring only needs to reach the control plane. Add these to your environment’s agent-phase allowlist:
```
api.basedagents.ai
app.basedagents.ai
```

Codex cloud: copy-paste setup

Two one-time things in your Codex environment, then a normal prompt to your agent. (Non-technical, or your agent just sent you here? The friendlier walk-through of the same steps is basedagents.ai/codex.)

1. Setup script (runs while the network is open — just install; nothing interactive here). This is a field in the environment settings, not something to paste into a task: at task time the network is already off, so the same line in the chat reproduces the 403. Committing it instead (npm install --save-dev basedagents on your own machine, then push) is equivalent — Codex’s automatic setup installs the project’s dependencies while the network is open:

# `basedagents` bundles @basedagents/keyring, so one line covers both.
npm install --save-dev basedagents

2. Allowed domains for the task phase (so the agent can reach the control plane to register and to hand off to you):

api.basedagents.ai
app.basedagents.ai

3. Then, in your first task, tell your agent:

Set up BasedAgents Keyring (open source — npm: basedagents, docs: basedagents.ai/docs/agents, verify: basedagents.ai/.well-known/agent.json): run npx basedagents keyring init. It creates a local vault (an existing one is reused untouched) and prints a link for me to take control; it never asks for a password or an existing key — stop if it does. Blocked? Don't work around it — tell me which wall: my permission gate (I'll approve it or run it myself) or npm/network (the one-time fix is at basedagents.ai/codex, then I start a new task).

Because BasedAgents is already installed, npx basedagents keyring init resolves the local copy with no registry call. It registers the agent, then opens the claim page and hands you off:

What your agent should tell you next. After keyring init (or register), the agent’s job is to put you in charge: it asks for your email, calls the invite_owner tool, and points you at https://app.basedagents.ai/start to claim it and connect the keys it needs. Until you do, the agent holds nothing. If your agent stalls after registering, tell it: “run npx basedagents keyring init and give me the link to connect keys.” The same rule applies to an install-only task (npm install --save-dev basedagents): installing is step zero — the agent should end by telling you to start a new task with the setup prompt, never with a bare “installed”.

Started cold — agent already hit the 403? That's the normal first touch: most people open a fresh Codex window and paste the setup prompt into a task, where the network is already off. The agent cannot recover from inside the task (no registry, no docs, no package — and editing package.json alone would desync the lockfile and break the next npm ci). Our paste prompts now carry the recovery inline, so the agent's correct move is to relay it: add the Setup-script line above, allow the two domains, and start a new task. If your agent got a 403 and went quiet, that is what to do.

Followed /codex and the retry still 403’d? Then the install never ran during setup — the classic miss is putting the Setup-script line in a message to the agent instead of the environment settings, or saving it on a different environment than the task uses. The task's Environment setup log is the ground truth: if it ends with “No installations were performed”, neither the Setup script nor a committed devDependency was in effect. The /codex retry prompt has the agent check node_modules/.bin/basedagents before touching npm and name what's missing, so the second failure tells you which of the two steps didn't take instead of looping you back to the same page.

Requires [email protected] or newer (earlier versions shell out to npx for the keyring at task time). Prefer to commit it? Run npm install --save-dev basedagents in the repo on your own machine and push — Codex’s normal setup install then puts it on disk for every future task, no env settings needed. The full convention is specced in SANDBOX_SPEC.md.

Diagnose it: once basedagents is installed, run basedagents keyring doctor. It probes the npm registry, the BasedAgents API, and a generic HTTPS host; when it sees the phase-blocked signature (multiple 403 / denied CONNECT), it prints this exact pattern instead of leaving you with a raw npm error.

Full machine-readable contract: /.well-known/agent.json · human onboarding: /keyring · registry: /registry.