This is the Your own agent help page of the Roma guide: what to do when a step of [https://roma.app/agents/your-own-agent.md](https://roma.app/agents/your-own-agent.md) fails. Read it only then.
## Your own agent help
When a step of [the Custom Agent page](https://roma.app/agents/your-own-agent.md) fails, the fix is here, by step.
### First the check
1. 401: Roma no longer takes your access; step 1 done. Road B (your own key): say the Replace key line. Road A (Roma Bridge): never a key; Roma Bridge says "Roma Bridge was connected again somewhere else, or removed in Roma. Run pair again." Run the `pair` line of step 2 again with `--agent `, or the person presses Connect again on your page; the Approve page is titled "Connect again" and reads "Roma Bridge on this computer gets new access. The old one stops working." (on a computer Roma Bridge did not run on before, it asks "Is this one of these agents?": "Pick .")
2. `register_agent` asks for `agentId`: say "Roma needs one update before I can say who I am. Your page still works. I read when opened." Then: "Open 's page in your browser: roma.app, Settings, Agents, press . Under Your key there is a line that starts GET /api/v1/triggers/. Copy that line and paste it here in this chat. It holds no secret." The trigger id is in it; the read address is this build's API origin plus that line. After the deploy the claim gives both.
3. `agent.pollUrl` null, `agent.reach.id` address or email: Roma reaches this record at an address or by mail (the page, Other ways Roma reaches you). Leave it so. Step 5 is that way's check, not the read.
Other ways, not part of the six steps: an address or mail, for a program with a public https address or an inbox (the page, Other ways Roma reaches you). Your page has no row that switches between them. They are not this road: do not move to them, and do not move a record away from them (the check, above). Moving ends the program's reads. There Roma sends or mails the delivery, there is no run report, pings come as section 6 says, and the check is the two rows under Connection on the page, Part 1 and Part 2 (whether can talk to Roma, and whether Roma can reach ), Part 2 with its Test button. A webhook's signing secret shows once in the Save your signing secret dialog and goes into the program's configuration, never the chat.
### The count
Nothing set up, the question "Is that so?": If no, the Claude or ChatGPT section.
No Agents page, or the claim says agents are not on: say "Roma cannot hand me tasks on this account yet. I can still keep your tasks there. Your setup has 2 steps instead of 6. Part 2, Roma reaching me, falls away." Then the 2-step road.
Agents page without Advanced: say "This account cannot add a program like me yet. Claude or ChatGPT can be handed tasks here; or I keep your tasks in Roma with 2 steps." Offer both.
**The 2-step road.** Make the file as in step 2. Say: "Step 1 of 2. A key lets me read and write your Roma. The key goes into one file only: , after ROMA_API_KEY=. Never paste it here. Open roma.app in your browser, Settings, Connections. Under API keys press Create key, then Copy. Tell me done." Then the paste line, with "Step 1 of 2." in front. Step 2 of 2 is yours: the claim with the key (`register_agent`, kind `other`), then `get_context`, the standing block as in step 4, then the one message of step 6 (the rules page, 4.3 and 7.10), starting "Step 2 of 2 is done. Roma is set up.", with the build's addresses. The second bullet (Delegate) is left out on this road: Roma cannot hand you tasks here. Then say: "You will not be told when it turns on. In a week send me the sentence from my page in Roma again; I check and tell you." A Connections key has no record and the claim refuses it ("A key claims by agentId"): no `register_agent`, no program read.
### Step 2. The access: a pairing, or a key by hand
Road A, the pairing:
1. No `npx` on that computer (Node is missing): road B. `npx -y roma-bridge` answers 404 or "not found" from npm: Roma Bridge is not published for this build yet. Do not try other package names, and install nothing else. Say: "Step 2 of 6. I cannot set this up today. Roma Bridge is not available to install yet. Nothing is wrong on your side. I can still read and write your tasks. Say step 2 again later." Or take road B. The command ends with "This Roma Bridge is too old to connect": an old copy ran. Run the same line with `npx -y roma-bridge@latest` in place of `npx -y roma-bridge`.
2. The browser did not open: the command printed a line starting Open; send that link, whole, with its `at=` part: "Step 2 of 6. Open this link in a browser on this computer: . It does not work on a phone or on another computer." The page reads "Open this on your computer" and has no Approve: it was opened on another device, or without the link's `at=` part. Send the link again. The command ends with "the pairing was approved, but not in a browser on this computer": the same cause. "Step 2 of 6. Nothing was connected. You approved in a browser on another device. The page must be open on this computer. I start it again." Nobody sits at this computer, or it has no browser: road B.
3. The page shows another code than yours: "Step 2 of 6. Press Deny. That page is not mine." Then run the command again. The code ran out (ten minutes), or the person pressed Deny: the command ends with the reason; say it in one line and run it again once.
4. The page says it adds a new agent, and an agent of the person already waits under another name (they pressed Get started before): the label did not match it. Before the Approve: "Step 2 of 6. Press Deny." Then run the command again with that agent's name as `--label` (the page, The count). After the Approve: you are the new agent, and the one that waits is left over. Say: "In Roma an agent named still waits. It is not me. You can remove it on its page: Settings, Agents, ." The page does not say , or it says already runs on a key: a running agent's key is never replaced, so the page makes a new agent by itself, named after the label (with a number when the name is taken). Nothing to pick: "Step 2 of 6. Press Approve." is the name in the command's closing lines from then on. Only a page that asks "Is this one of these agents?" could not decide (several agents of the person still wait and none has the name): "Step 2 of 6. Pick the one you made for me, or Add it as a new agent." The person pressed No on "Connect this computer?": nothing was connected, and the command ends saying so. The browser was signed in to another Roma account: "Step 2 of 6. Sign in to Roma with your own account in that browser. Then tell me done." Then run the command again. With `--account`, the same case ends "the Roma account approved, not . Nothing was connected".
5. The closing lines say Roma Bridge could not be set to start at login, or the computer is not a Mac: the lines say "Roma Bridge is running now, in this window. It stops when you close the window." The command does not end after them: it is Roma Bridge from then on. Do not wait for it to end, and do not stop it. It runs inside your session, so it stops when your session ends. Say so, and give the person the line it printed under "To start it again later:" to run in a terminal window of their own (the page, step 2, item 1).
6. The command's posts show as "Your agent", or 's working line on the task never ends: what the command starts wrote through another Roma connection. Register the agent's own connection (the page, step 2, item 3) and name that server in the instruction the command hands on. `npx -y roma-bridge mcp --agent ''` ends with "This agent was removed in Roma. Set it up again.": no agent of that name is in Roma Bridge's file. Roma may have added a number to the name (" (2)"): the name in the pairing's closing lines is the one to use, and `npx -y roma-bridge status` names the agents that are there. One that is gone needs the pairing again.
7. The task shows no link to where the work happened: the command wrote nothing into the file `ROMA_SESSION_FILE` names, or wrote a link Roma does not keep (only https, or an app's own link). One JSON line with `url` or `id`.
8. The task reads Done while the work still goes on: the command exited before the work was finished, and Roma took the exit for the end (the page, step 2, what the command must keep to). Make the command wait for the work. The task reads Failed: the command exited with another code than 0. The chat reads "Stopped after 30 minutes. Assign it again to continue.": the run passed its limit; shorter runs, or a higher `maxRunMinutes`.
9. The command cannot run, or cannot reach Roma, and you may not ask for more access (a session whose sandbox has no network): do not try again. Say: "Step 2 of 6. I cannot reach Roma from this session. It has no network access. Start me again with network access. Then send me the sentence again."
10. The person said done and the command is gone with no closing lines: it was stopped before the approval reached it. `npx -y roma-bridge status` says whether Roma Bridge is connected. Not connected: run the pairing again, this time so it keeps running after your turn ends, and say: "Step 2 of 6. That did not finish. I start it again. The Roma page shows a new code."
11. `npx -y roma-bridge install` says it is waiting for a task to finish: Roma Bridge is in the middle of one and ends it first; the line says how long at most. Let it wait. It ends with "macOS did not start Roma Bridge": wait a minute and run it again.
Road B, the key by hand (a program that runs by itself; an agent Roma Bridge runs has no Key row, its page offers Connect again):
1. No Make a key on the Key row: the row holds a key already; the Replace key line below. Dialog closed before Copy, or key lost, the Replace key line: "Step 2 of 6. Open 's page in your browser: >. On the Key row press Replace key. The old key is dead. Copy the new one. Paste it after ROMA_API_KEY= in , nowhere else. Tell me done."
2. A key pasted in the chat: never use or repeat it. Say "Step 2 of 6. That key is dead now. On the Key row press Replace key and put the new one in the file, after ROMA_API_KEY=."
### Step 3. Connect and claim
1. "A key claims by agentId": a Connections key. Say the key line and the paste line of step 2.
2. Agents not on: the 2-step road.
3. 401: check header and file, then the Replace key line.
The check, `get_context`: its `agent` block must carry `kind: "other"` and , not the client's name (Cursor). Else claim again. A second claim fixed it.
### Step 5. Start the program's reads
If the person must start it: "Step 5 of 6. The program is how Roma reaches me; it reads your tasks. This step needs a terminal on a computer. Where are you right now: at a computer, or on your phone? Say computer or phone." Wait. Then: "Step 5 of 6. In the folder , run this one line: . Leave that window open. It is the program that reads your tasks. Tell me done."
1. 403: another agent's key, the Replace key line. 409: disabled, the read-me line: "In Roma open Settings, Agents, . On a computer this link opens it: . Read me the two rows under Connection, Part 1 and Part 2. One says whether can talk to Roma, the other whether Roma can reach ." 400 `notPollable`: an address or mail, First the check above.
The check: `register_agent` with `kind: "other"` again; its answer's `agent.canBeHandedWork` is true once Roma reached you (`agent.reachableAt` says when). Not yet: wait, claim again, up to three times over about ninety seconds, and say "Step 5 of 6. Roma is testing the road to me. Nothing for you to do." Only when it stays false: check that the program runs and reads `ROMA_POLL_URL` with the key from the file, then ask once: "Step 5 of 6. In Roma open Settings, Agents, . On a computer this link opens it: . Read me the two rows under Connection. The row 'Part 1. can talk to Roma' should read Connected just now. The row Part 2 should read Reached just now." Not reached: say "Step 5 of 6. Press Test on the row 'Part 2. Roma can reach '. Then read me that row again." Still not reached: stop. Say: "Step 5 of 6. The page says Roma cannot reach me. I cannot fix this from here. We try again later from your computer, step 5 again." Road A, before any of that: make sure the claim went through the line of step 2, item 4. A claim through a sign-in of your own reads another record, and that one stays false for good.
### Step 6. How this works from now on
A read made before the claim read true may not name you yet (the list's line follows the proof on the next call, a few seconds at most); the proof is the claim's `agent.canBeHandedWork` (step 5), and `list_lists` again right after the claim reads true gives the name, once more a few seconds later if not. Never ask the person to open a menu and look, and never call it inconsistent to them (the rules page, 7.6).