Skip to content

Lifecycle

The agensai npm package exposes three commands. Only one is user-facing.

CommandWho runs itWhat it does
agensai pair <token>You, onceGenerates the orchestrator key on your device, redeems the dashboard pairing token, writes MCP config into Claude Desktop / Cursor / Claude Code.
agensai serveYour IDEStarts the MCP server over stdio. Loads the orchestrator key from ~/.agensai/, claims a single-active-device lockfile, opens a loopback RPC port for the dashboard's retire and whoami queries.
agensai disconnect [--purge]You or the dashboardStops the running daemon. With --purge, wipes ~/.agensai/.

pair

npx agensai pair <token>

The token comes from the dashboard at app.agensai.xyz. It carries your JAW API key and a one-time opaque redemption code.

What happens:

  1. Key generation. A fresh ECDSA private key is generated in-process. The dashboard never sees it.
  2. SA derivation. The smart-account address is derived from the key on chain 1 (mainnet) and chain 84532 (Base Sepolia). Only the addresses go back to the dashboard, used for ENS records and as the recovery target.
  3. Token redemption. The dashboard's /api/pairing/redeem validates the token and returns the orchestrator's assigned ENS subname (<root>-orc.agensai.eth).
  4. Local storage. The orchestrator key is written to ~/.agensai/orchestrator.key with mode 0600. Same plaintext + file-permission pattern as ~/.jaw/keystore.json.
  5. MCP config. Stdio entries are written to Claude Desktop, Cursor, and Claude Code configs:
{
  "mcpServers": {
    "agensai": {
      "command": "npx",
      "args": ["-y", "agensai", "serve"]
    }
  }
}

After pairing, restart your IDE so the MCP server loads.

Re-pairing

agensai pair refuses to overwrite an existing orchestrator unless you pass --yes. To switch orchestrators cleanly:

agensai disconnect --purge
npx agensai pair <new-token>

serve

Your IDE spawns this. You normally do not run it yourself.

npx -y agensai serve [--rpc-port 5181] [--no-rpc]

Behavior:

  • Loads the orchestrator key from ~/.agensai/.
  • Claims ~/.agensai/serve.lock. Only one device at a time can hold the lock.
  • Starts the MCP stdio transport for the IDE.
  • Starts a loopback RPC server (default 127.0.0.1:5181) so the dashboard can list local agents, query which orchestrator this device is paired as, and assist the retire flow without leaving the browser.

Exits with code 1 if no orchestrator is paired.

disconnect

agensai disconnect          # stop the daemon
agensai disconnect --purge  # stop AND wipe ~/.agensai/

--purge is irreversible. It removes the orchestrator key, the agent keystore, the config pointer, and the lockfile. Anything you funded into the orchestrator's smart account is still on-chain; recover it from the dashboard's main account before purging if you want it back.

Files in ~/.agensai/

FileWhat it holds
orchestrator.keyPlaintext ECDSA private key, mode 0600.
orchestrator.jsonPointer: ENS, SA addresses per chain, JAW API key, hostname, paired timestamp.
owner.keystore.jsonMirror of the orchestrator key in JAW SDK keystore shape (read by MCP tools).
agents/<name>/Per-agent session keys + pointers. Populated as you spawn agents through MCP.
serve.lockActive-device lockfile written by serve.
config.jsonDefault chain id and other knobs.

All files are mode 0600. Treat the directory as you would ~/.ssh/.