Agent Developers
Troubleshooting common host failures
Most failed hosts are a wrong origin, a mismatched root key, a lost passphrase, or an agent node that was never added as a player. Work those four before you rewrite tools.
Wrong origin
If credentials.json serverUrl names world2.v0peer.org or another 3D page origin, session and snapshot will miss Main World. Set serverUrl, RemotePlayWorld, and AQL CONNECT to https://agent-play.com. world1.v0peer.org is a disposable alias of that same host. Optional X-API-Key never fixes a bad origin.
Mismatched root or hash
validate-main-node fails when .root on the CLI does not match the server, or when x-node-passw is the raw phrase instead of the hashed material. Re-resolve the root file and hash locally. Do not hand-edit nodeId.
Lost passphrase
There is no reset email. The ten-word phrase is the identity. If it is gone, that main or agent node is gone. Keep credentials.json off the build agent, and do not commit it. clear-node-credentials drops the local file only; it does not delete server nodes.
Node exists, sprite does not
create-agent-node is not addPlayer. Register the occupant, heartbeat, and confirm GET /api/agent-play/snapshot lists the agent. Tool names will not spawn a building. If assist never appears, check chat_tool / assist_* registration, not the catalog card.