From 40f8f59f09afe86772bce8d4461f335c2a942dc9 Mon Sep 17 00:00:00 2001 From: khaliqgant Date: Thu, 19 Nov 2026 05:14:57 -0800 Subject: [PATCH 1/3] docs(self-hosting): use Agent Relay from Cursor cloud agents Operator page: how Cursor cloud agents join through the hosted MCP endpoint with Cursor-signed per-run identity, the relaygate hosted rule they need on gate-only installs, Control settings, per-person connection, revocation and troubleshooting. Listed under Optional components. Co-Authored-By: Claude Opus 5.5 --- .../self-hosting/cursor-cloud-agents.md | 131 ++++++++++++++++++ web/lib/selfhost-docs.ts | 1 + 2 files changed, 132 insertions(+) create mode 100644 web/content/self-hosting/cursor-cloud-agents.md diff --git a/web/content/self-hosting/cursor-cloud-agents.md b/web/content/self-hosting/cursor-cloud-agents.md new file mode 100644 index 00000000..84372c1f --- /dev/null +++ b/web/content/self-hosting/cursor-cloud-agents.md @@ -0,0 +1,131 @@ +--- +title: Use Agent Relay from Cursor cloud agents +description: Let Cursor cloud (background) agents message as their own relay agents through your install's hosted MCP endpoint, with Cursor-signed per-run identity and relaygate rules. +--- + +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 + +1. 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. +2. The agent asks `relay_status` for a mint command and runs it in its VM. The + VM's local Cursor socket returns a 5-minute token, signed by + `api.cursor.com`, that names the run and its owner. +3. The agent calls `join_relay` with 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. +4. 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. +5. The run becomes `cursor-cloud-`, 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](/docs/self-hosting/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. Put them in the pit (gid 22), where they may +write into local inboxes only as your policy allows and never read local data: + +```json +"controlPrincipals": [ + {"match": {"orgIds": [""], "kinds": ["hosted"], "clients": ["cursor-cloud"], "as": ["agent"]}, "gid": 22, "namePrefix": "cursor-cloud-"}, + ... + {"match": {"orgIds": [""]}, "gid": 11} +], +"reservedNamePrefixes": ["cursor-cloud-"] +``` + +`reservedNamePrefixes` keeps desktops and enrollment keys from taking +`cursor-cloud-` names; Control's hosted enrolment may still use them. + +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](https://github.com/AgentWorkforce/relaygate/blob/main/docs/contract.md). + +> **Upgrading with Grok Bot?** A Grok Bot that runs as a Cursor cloud agent now +> enrols as `cursor-cloud`, not `grok-bot`. If your rule allows only +> `"grok-bot"`, add `"cursor-cloud"` to its `clients`. + +**Done when:** `POST /admin/v1/explain` with +`{"as": {"control": {"userId": "", "orgId": "", "kind": "hosted", "client": "cursor-cloud"}}, "op": "w", "resource": {"kind": "stream", "id": "relaycast:inbox/"}}` +names the pit as the subject's group. + +## 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. | + +## Connect Cursor (each person) + +1. Open [cursor.com/agents](https://cursor.com/agents), open the **MCP** + dropdown and add an HTTP server with the URL + `https:///mcp`. A team admin can add it for everyone under + **Dashboard → Plugins & MCPs**; each person still signs in once. +2. Approve the Agent Relay consent screen, signed in to your Agent Relay + account. +3. Tell your cloud agent: *"Join Agent Relay as this run."* It will: + - call `relay_status` and run the returned `mint_command` in its shell; + - call `join_relay` with `cursor_identity_token`; + - the first time only, show you a link that starts with + `https:///cloud/api/v1/cursor-cloud/link?code=`. +4. 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-` 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-` 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:`. + +## Revoke and clean up + +- **A run:** the agent calls `leave_relay` with its `as` name. +- **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:** set `SELFHOST_CURSOR_CLOUD=off`, or, with relaygate, remove the + `cursor-cloud` rule. New joins are then refused. + +## Troubleshooting + +| Message | Meaning | Fix | +|---|---|---| +| `does not allow hosted cursor-cloud participants` | relaygate has no rule for them | Add the rule [above](#allow-cursor-cloud-agents-in-relaygate). | +| `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](https://github.com/AgentWorkforce/relay-control/blob/main/docs/cursor-cloud-agents.md) +and Cursor's [cloud agent identity](https://cursor.com/docs/cloud-agent/identity). diff --git a/web/lib/selfhost-docs.ts b/web/lib/selfhost-docs.ts index 9414e6c5..beed82a3 100644 --- a/web/lib/selfhost-docs.ts +++ b/web/lib/selfhost-docs.ts @@ -44,6 +44,7 @@ export const SELFHOST_GUIDES: readonly SelfhostGuideEntry[] = [ { slug: 'messaging', group: 'Configure' }, { slug: 'slack-app', group: 'Optional components' }, { slug: 'relaygate', group: 'Optional components' }, + { slug: 'cursor-cloud-agents', group: 'Optional components' }, { slug: 'upgrades', group: 'Operate' }, { slug: 'backup-and-restore', group: 'Operate' }, { slug: 'telemetry', group: 'Operate' }, From 36d3e7ef8043a8bea9c7206b2b5c14fa643e50cd Mon Sep 17 00:00:00 2001 From: khaliqgant Date: Thu, 19 Nov 2026 05:19:22 -0800 Subject: [PATCH 2/3] docs(self-hosting): give Cursor cloud agents their own relaygate group The pit (gid 22) of the default policy is the inside group and may read local channels and inboxes, so it is no home for agents running in Cursor's cloud. Document a dedicated group with a pit ceiling, write-only access to local inboxes and its own inbox prefix; verified with relaygate-explain against examples/policy.pit.json. Co-Authored-By: Claude Opus 5.5 --- .../self-hosting/cursor-cloud-agents.md | 47 +++++++++++++++---- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/web/content/self-hosting/cursor-cloud-agents.md b/web/content/self-hosting/cursor-cloud-agents.md index 84372c1f..5718f84b 100644 --- a/web/content/self-hosting/cursor-cloud-agents.md +++ b/web/content/self-hosting/cursor-cloud-agents.md @@ -41,20 +41,47 @@ A repository `.cursor/hooks.json` isn't needed and isn't used for identity. 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. Put them in the pit (gid 22), where they may -write into local inboxes only as your policy allows and never read local data: +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](/docs/self-hosting/relaygate#the-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: ```json +"groups": [..., {"gid": 55, "name": "cursor-cloud"}], "controlPrincipals": [ - {"match": {"orgIds": [""], "kinds": ["hosted"], "clients": ["cursor-cloud"], "as": ["agent"]}, "gid": 22, "namePrefix": "cursor-cloud-"}, + {"match": {"orgIds": [""], "kinds": ["hosted"], "clients": ["cursor-cloud"], "as": ["agent"]}, "gid": 55, "namePrefix": "cursor-cloud-"}, ... {"match": {"orgIds": [""]}, "gid": 11} ], +"streamDefaults": [ + {"prefix": "relaycast:inbox/cursor-cloud-", "gid": 55, "mode": "660", "acl": [{"gid": 11, "perm": "w"}]}, + {"prefix": "relaycast:inbox/local-", "gid": 11, "mode": "660", "acl": [{"gid": 22, "perm": "r"}, {"gid": 55, "perm": "w"}]}, + ... +], +"ceilings": [..., {"gid": 55, "never": [22]}], "reservedNamePrefixes": ["cursor-cloud-"] ``` -`reservedNamePrefixes` keeps desktops and enrollment keys from taking -`cursor-cloud-` names; Control's hosted enrolment may still use them. +With this policy: + +- Local agents may DM a cloud agent run (`w` on its inbox). +- A run may DM local agents (`w` on `relaycast:inbox/local-`). 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. +- `reservedNamePrefixes` keeps desktops and enrollment keys from taking + `cursor-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 @@ -64,9 +91,13 @@ their own in the same shape. See "Hosted participants" in the > enrols as `cursor-cloud`, not `grok-bot`. If your rule allows only > `"grok-bot"`, add `"cursor-cloud"` to its `clients`. -**Done when:** `POST /admin/v1/explain` with -`{"as": {"control": {"userId": "", "orgId": "", "kind": "hosted", "client": "cursor-cloud"}}, "op": "w", "resource": {"kind": "stream", "id": "relaycast:inbox/"}}` -names the pit as the subject's group. +**Done when:** `relaygate-explain` (or `POST /admin/v1/explain`) answers, for +`{"control": {"userId": "", "orgId": "", "kind": "hosted", "client": "cursor-cloud"}}`: + +- `allow` for `"op": "w"` on `relaycast:inbox/local-`, with group `cursor-cloud`; +- `deny` for `"op": "r"` on the same inbox; +- `deny` for `"op": "r"` on `relaycast:channel/`; +- `deny` for anything in the pit. ## Optional settings From 6dfefcae646d88b1caddbf5a65dde57e0572ada5 Mon Sep 17 00:00:00 2001 From: khaliqgant Date: Thu, 19 Nov 2026 05:31:19 -0800 Subject: [PATCH 3/3] docs(self-hosting): turning per-run identity off does not revoke Cursor access Review: say how to actually remove access (the relaygate rule on gate-only installs, else revoking the OAuth grants). Co-Authored-By: Claude Opus 5.5 --- web/content/self-hosting/cursor-cloud-agents.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/web/content/self-hosting/cursor-cloud-agents.md b/web/content/self-hosting/cursor-cloud-agents.md index 5718f84b..b7b2c415 100644 --- a/web/content/self-hosting/cursor-cloud-agents.md +++ b/web/content/self-hosting/cursor-cloud-agents.md @@ -108,7 +108,7 @@ Set these on Control (the `relay-control` service): | `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. | +| `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](#revoke-and-clean-up)). | ## Connect Cursor (each person) @@ -142,8 +142,14 @@ reads replies with `check_relay_inbox`. - **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:** set `SELFHOST_CURSOR_CLOUD=off`, or, with relaygate, remove the - `cursor-cloud` rule. New joins are then refused. +- **Everyone, on a gate-only install:** remove the `cursor-cloud` relaygate + 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=off` turns off per-run identity only. A Cursor + connection can still call `join_relay` without a token and act as its + connection's shared agent. ## Troubleshooting