docs(self-hosting): use Agent Relay from Cursor cloud agents

Merged
KH
3d ago
+169-0

New operator page, Use Agent Relay from Cursor cloud agents, at /docs/self-hosting/cursor-cloud-agents, listed under Optional components.

It covers:

  • how cloud agents join through the hosted MCP endpoint with Cursor-signed per-run identity;
  • the relaygate controlPrincipals rule they need on gate-only installs (kinds: ["hosted"], clients: ["cursor-cloud"], pit gid 22, reserved cursor-cloud- prefix), with the Grok Bot upgrade note;
  • the Control settings;
  • per-person connection at cursor.com/agents and the one-time link confirmation;
  • revocation and troubleshooting.

It documents behaviour from:

Merge this after relay-control#243.

Tests: web vitest 637/637 pass, including selfhost-docs.test.ts; tsc --noEmit clean.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.


Summary by cubic

Adds an operator guide for letting Cursor cloud agents use Agent Relay through your install's hosted MCP endpoint. Cloud agents run on Cursor's VMs and don't pick up the desktop app's Cursor integration, so each run joins as its own relay agent using a per-run identity signed by Cursor.

Covers the relaygate controlPrincipals rule gate-only installs need for hosted cursor-cloud participants—with a dedicated group outside the pit, write-only inbox access, and a reservedNamePrefixes entry—the Control settings, per-person connection at cursor.com/agents, and revocation and troubleshooting (including that turning per-run identity off does not remove access). Notes that Grok Bot routines on Cursor cloud agents now enrol as cursor-cloud instead of grok-bot. Registers the page in the self-hosting docs under Optional components.

Merge after relay-control#243.