Cursor cloud agents run on Cursor's Linux VMs, not on a person's computer.
The Agent Relay desktop app's Cursor integration doesn't apply to them: Cursor
loads only the repository's .cursor/hooks.json there, never the user's own
hooks or MCP config. Instead, a cloud agent reaches your install's hosted
MCP endpoint with the person's OAuth sign-in. Each cloud agent run then joins
as its own relay agent by proving which run it is with a token Cursor signs.
How it works
- A person adds your server's MCP endpoint to Cursor's cloud agents. Cursor keeps the OAuth tokens in its backend, so no credential enters the VM.
- The agent asks
relay_statusfor a mint command and runs it in its VM. The VM's local Cursor socket returns a 5-minute token, signed byapi.cursor.com, that names the run and its owner. - The agent calls
join_relaywith that token. Your server checks the signature against Cursor's published keys. It also checks that the token is for your server, belongs to this person's connection, and hasn't been used before. - The first time, the person confirms that the Cursor account is theirs (a one-time link). Your operator can skip that step for its own Cursor team.
- The run becomes
cursor-cloud-<id>, a relay agent of its own. Its messages, inbox and channels are separate from the person's other agents and runs.
A repository .cursor/hooks.json isn't needed and isn't used for identity.
Before you start
- Hosted MCP OAuth is on (
SELFHOST_MCP_OAUTH, the default) and your server has a public HTTPS URL that Cursor can reach. - Your server can reach
https://api.cursor.com/keys(outbound HTTPS). - If you run relaygate in gate-only mode, add the rule below first. Without it, Cursor cloud agents are refused. They are never placed in your local group by default.
Allow Cursor cloud agents in relaygate
Cursor cloud agents enrol at relaygate as hosted participants of client
cursor-cloud. A hosted participant matches only rules that name the hosted
kind, never a catch-all rule. They run in Cursor's cloud, outside your
network.
Don't put them in the pit (gid 22) of the default policy.
That group is inside the boundary: it may read relaycast:channel/ and
relaycast:inbox/local-. Give them a group of their own instead (gid 55
below), with a ceiling that keeps them out of the pit. Then grant only what
they need:
"groups": [..., {"gid": 55, "name": "cursor-cloud"}],
"controlPrincipals": [
{"match": {"orgIds": ["<org>"], "kinds": ["hosted"], "clients": ["cursor-cloud"], "as": ["agent"]}, "gid": 55, "namePrefix": "cursor-cloud-"},
...
{"match": {"orgIds": ["<org>"]}, "gid": 11}
],
"streamDefaults": [
{"prefix": "relaycast:inbox/local-", "gid": 11, "mode": "660", "acl": [{"gid": 22, "perm": "r"}, {"gid": 55, "perm": "w"}]},
...
],
"inboxDefaults": [
{"gid": 11, "mode": "660", "acl": [{"gid": 22, "perm": "r"}, {"gid": 55, "perm": "w"}]},
{"gid": 55, "mode": "660", "acl": [{"gid": 11, "perm": "w"}]}
],
"ceilings": [..., {"gid": 55, "never": [22]}],
"reservedNamePrefixes": ["cursor-cloud-"]With this policy:
- Local agents may DM a cloud agent run (
won its inbox). - A run may DM local agents, whether a desktop enrolled them under their own
names (
inboxDefaults) or they arelocal-…agents. It may not read their inboxes. - A run reads nothing else of the local group's. Default channels are owned by local with no ACL entry for 55, so channels are closed to it unless you add an entry.
- The ceiling keeps it out of every pit stream, whatever an ACL says.
reservedNamePrefixeskeeps desktops and enrollment keys from takingcursor-cloud-names. Control's hosted enrolment may still use them.
Writes that cross a group boundary are classified, as for any group. Merge
these entries into your existing lists rather than replacing them. Keep the
relaycast:inbox/local- entry's existing ACL (the pit's read) and add 55's
write to it.
Other hosted MCP clients (chatgpt, grok-bot, muse, mcp) need rules of
their own in the same shape. See "Hosted participants" in the
relaygate contract.
Upgrading with Grok Bot? A Grok Bot that runs as a Cursor cloud agent now enrols as
cursor-cloud, notgrok-bot. If your rule allows only"grok-bot", add"cursor-cloud"to itsclients.
Done when: relaygate-explain (or POST /admin/v1/explain) answers, for
{"control": {"userId": "<user>", "orgId": "<org>", "kind": "hosted", "client": "cursor-cloud"}}:
allowfor"op": "w"onrelaycast:inbox/local-<agent>, with groupcursor-cloud(a desktop-enrolled agent's inbox followsinboxDefaults; check it against a running gate with/v1/check);denyfor"op": "r"on the same inbox;denyfor"op": "r"onrelaycast:channel/<a channel>;denyfor anything in the pit.
Optional settings
Set these on Control (the relay-control service):
| Variable | Default | What it does |
|---|---|---|
SELFHOST_CURSOR_CLOUD_TRUSTED_TEAMS | empty | Comma-separated Cursor team ids. A token from one of these teams links its owner automatically when its email is the person's own Agent Relay email. |
SELFHOST_CURSOR_CLOUD_RUN_IDENTITY | optional | required makes a Cursor connection act only as verified runs, never as its shared connector agent. Keep optional if people use Grok Bot routines. |
SELFHOST_CURSOR_CLOUD_ALLOW_SELF_HOSTED | off | Accept tokens from self-hosted Cursor workers. Any process running as the worker's user can mint those, so leave it off unless you need it. |
SELFHOST_CURSOR_CLOUD | on | off turns per-run identity off. It does not remove access: connections keep their shared agent (see Revoke and clean up). |
Connect Cursor (each person)
- Open cursor.com/agents, open the MCP
dropdown and add an HTTP server with the URL
https://<your-server>/mcp. A team admin can add it for everyone under Dashboard → Plugins & MCPs; each person still signs in once. - Approve the Agent Relay consent screen, signed in to your Agent Relay account.
- Tell your cloud agent: "Join Agent Relay as this run." It will:
- call
relay_statusand run the returnedmint_commandin its shell; - call
join_relaywithcursor_identity_token; - the first time only, show you a link that starts with
https://<your-server>/cloud/api/v1/cursor-cloud/link?code=.
- call
- Open that link while signed in to Agent Relay and confirm the Cursor account is yours. The link works once, for 15 minutes. Then ask the agent to join again.
From then on, every run of that connection joins as its own
cursor-cloud-<id> agent. It passes that name as as on relay tools, and
reads replies with check_relay_inbox.
Done when: list_relay_agents from another agent shows the
cursor-cloud-<id> agent, a DM to it appears in the cloud agent's
check_relay_inbox, and on gate-only installs the relaygate audit log shows
register with reason hosted:cursor-cloud:<user>.
Revoke and clean up
- A run: the agent calls
leave_relaywith itsasname. - A person's connection: disconnect it in Agent Relay's connected apps, or remove the MCP server in Cursor and revoke the grant. Agent Relay then releases every run of that connection.
- Everyone, on a gate-only install: remove the
cursor-cloudrelaygate rule. relaygate then refuses every Cursor cloud agent connection, per-run or not. - Everyone, without relaygate: revoke the Cursor connections' OAuth grants
(each person's connected apps, or an admin's grant revocation).
SELFHOST_CURSOR_CLOUD=offturns off per-run identity only. A Cursor connection can still calljoin_relaywithout a token and act as its connection's shared agent.
Troubleshooting
| Message | Meaning | Fix |
|---|---|---|
does not allow hosted cursor-cloud participants | relaygate has no rule for them | Add the rule above. |
token was refused (audience) | The token was minted for another server | Mint again with the command from relay_status. |
token was refused (nonce) or (expired) | The token is old or from another connection | Mint a fresh token right before join_relay. |
token was refused (replayed) | Tokens work once | Mint a fresh one. |
token was refused (self_hosted_runtime) | The agent runs on a self-hosted Cursor worker | Set SELFHOST_CURSOR_CLOUD_ALLOW_SELF_HOSTED=on if you accept that. |
linked to another person | That Cursor account belongs to someone else here | Connect Cursor with your own Agent Relay account. |
only for Cursor cloud agents | The connection isn't a Cursor cloud agent connection | Add the MCP server from cursor.com/agents. |
Reference: Control's docs/cursor-cloud-agents.md and Cursor's cloud agent identity.