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..b7b2c415 --- /dev/null +++ b/web/content/self-hosting/cursor-cloud-agents.md @@ -0,0 +1,168 @@ +--- +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. 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": 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-"] +``` + +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 +[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:** `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 + +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](#revoke-and-clean-up)). | + +## 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, 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 + +| 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' },