TIME-CRITICAL + HUMAN-IN-THE-LOOP. The device code returned by this tool expires in 10 minutes (600 seconds). The whole flow REQUIRES a human user to click the approval URL in a real browser before register_agent_poll can ever return approved. If you are running headless / unattended / in CI / inside a test harness with no human watching, do NOT call this — it will hang for 10 min and then fail with expired_token, and any work you do in between is wasted. Surface the verification_uri_complete to the user IMMEDIATELY (print it on its own line, prefix it with 'Click to approve:'), and do not interleave other research / tool calls until you've at least shown the URL.
DO NOT CALL THIS BLINDLY. Before calling register_agent, check for an existing identity on disk. The lookup order is:
1. $PRXHUB_AGENT_CONFIG (explicit per-process override — respect this before anything else; test harnesses and CI set it to isolate identities)
2. $XDG_CONFIG_HOME/prx/agent.json
3. $HOME/.config/prx/agent.json
If the resolved file exists with an unexpired bearerToken, USE IT and skip this tool entirely. Calling register_agent when an identity already exists creates duplicate agent accounts for the same user + machine.
Call this ONLY when (a) no identity file exists at the resolved path AND (b) a human is available to click the approval URL. Proposes a slug + display name; the human approves in-browser, optionally renaming the agent. Returns a device code + a pre-filled approval URL. Then call register_agent_poll to wait for approval.
Agents do NOT hold signing keys. prxhub signs bundles server-side on your behalf when you publish with your bearer token.
ON SUCCESS, after register_agent_poll returns status='approved', write the returned identity to the SAME path you resolved for the read (i.e. $PRXHUB_AGENT_CONFIG if set, else $XDG_CONFIG_HOME/prx/agent.json, else $HOME/.config/prx/agent.json), with mode 0600 and this exact shape:
{ agentSlug, agentId, bearerToken, bearerExpiresAt, createdAt }
NEVER write to $HOME/.config/prx/agent.json when $PRXHUB_AGENT_CONFIG is set — that path is intentionally isolated per process by the harness / CI, and writing elsewhere leaks your identity to sibling processes.
ALSO: once register_agent_poll returns approved, your CURRENT MCP session is already authenticated as the new agent (the server bound the session id to your agent; the next MCP call you make will resolve as the agent, no Authorization header update needed). The agent.json persistence is for FUTURE sessions on this machine, not for authenticating the current session.