Add Cursor Cloud Agents integration guide - #233
Open
kylemclaren wants to merge 17 commits into
Open
Conversation
Documents running Cursor Self-Hosted Machines on Sprites: a spawn hook for `agent worker controller` that gives each claimed request its own Sprite, runs the worker as a supervised service with a Tasks heartbeat, and uses Sprite pause/wake (instead of snapshot/restore) for Cursor's hibernation flow. Refs superfly/sprites-ecosystem#100 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEkY7WWtGfEue9LQqBtDYa
Contributor
Preview Deployment
Commit: |
Contributor
Lighthouse Results
|
Contributor
E2E Test Results✅ Tests success Ran against: https://pr-233-superfly-sprites-docs.fly.dev |
Found while testing a My Machines worker in a Sprite: with legacy privacy mode on, the worker authenticates and reports running but reconnects to the bridge endlessly and never appears in Cursor. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEkY7WWtGfEue9LQqBtDYa
- Enterprise is no longer a prerequisite: the guide starts with a personal My Machines worker (any Cursor plan) and treats team pools as the optional scale-out section. - spawn.sh now serves both modes: run it directly with CURSOR_WORKER_NAME for a personal machine, or as the controller's --spawn hook. It clones CURSOR_REPO_URL on first create. cursor-worker.sh picks --name or --pool accordingly. Both paths re-tested against ecosystem-testing. - New ExpandableCode React island collapses long code blocks behind an Expand / Collapse toggle; used for the two scripts. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEkY7WWtGfEue9LQqBtDYa
Code blocks are the same near-black in both modes, so fading to --sl-color-bg produced a light smear over dark code in light mode. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEkY7WWtGfEue9LQqBtDYa
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEkY7WWtGfEue9LQqBtDYa
spawn.sh installs the Linux desktop packages when --computer-use or --share-desktop is requested and writes a startxfce4 wrapper that drops capabilities (bubblewrap refuses to run with them) and runs xfwm4 under a session bus, since xfce4-session never launches the window manager here. spawn.sh also restarts an existing service instead of only starting a stopped one, and cursor-worker.sh no longer self-stops when the runtime is the one stopping it, which broke restarts. Verified on a My Machines worker: both displays up, worker registered, Sprite held active. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEkY7WWtGfEue9LQqBtDYa
The startxfce4 wrapper only got the window manager up; anything GTK the agent launched still aborted on its first icon load, because bubblewrap (used by GTK's image loaders) refuses to run from a process carrying capabilities. spawn.sh now diverts /usr/bin/bwrap behind a wrapper that drops capabilities. Full Xfce sessions and sandboxed Chrome verified rendering on the worker's displays. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEkY7WWtGfEue9LQqBtDYa
Cursor's shell tool kills the command's process group on return, so a browser started as a background job dies immediately. spawn.sh now writes a user-level rule (~/.cursor/rules/sprite-desktop.mdc) telling the agent to launch GUI apps with setsid -f and screenshot afterwards. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEkY7WWtGfEue9LQqBtDYa
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UEkY7WWtGfEue9LQqBtDYa
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
With desktop sharing on, the current Cursor CLI gives the agent shell the shared display but screenshots the first one, so agents never see the windows they open. Document the mismatch and default to --computer-use alone. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Chrome's welcome dialog opens instead of a browser window on a fresh profile; agents miss it and conclude Chrome crashed. Add --no-first-run to the rule and the First Run marker to the install one-liner. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
CURSOR_INSTALL_CHROME=1 makes spawn.sh install Google Chrome and front the chrome commands with a wrapper that always detaches and skips the first-run and crash-restore dialogs, so any launch style an agent uses produces a browser window that survives the shell tool's process-group kill. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The guide now walks through the Integrations tab in the Fly.io dashboard instead of the spawn.sh and cursor-worker.sh scripts, and is a third of the length. The ExpandableCode component only existed for those scripts, so it goes too. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an integration guide for running Cursor Self-Hosted Machines on Sprites, plus a sidebar entry under Integrations.
agent worker controllerthat gives each claimed request its own Sprite, installs the Cursor CLI, and runs the worker as a supervised service with a Tasks heartbeat.CURSOR_WAKE=1, and the hook restarts the worker in the same Sprite with its workspace intact.--clone-git-reposvs. cloning in the hook), network egress, cleanup, and troubleshooting.Testing
pnpm buildandpnpm lintpass.