Skip to main content
Cursor Self-Hosted Machines let Cursor run the agent loop and the model while the agent’s tool calls, the commands it runs and the files it edits, execute on a machine you control. The Sprites dashboard turns a Sprite into one of those machines with a form: paste a Cursor API key, name the machine, and it appears under My Machines in Cursor. No terminal, no scripts. This works on any Cursor plan with Cloud Agents.

​
How it works

Each Cursor machine is one Sprite. On it, a cursor-worker service runs the Cursor CLI’s worker, which opens a single outbound connection to Cursor. Cursor forwards the agent’s tool calls over that connection and the worker executes them in the Sprite’s workspace. Nothing connects inbound. While the worker is connected, the service holds the Sprite active through the Tasks API. When no agent has used the machine for 10 minutes, the worker exits, the hold is released, and the Sprite pauses with its workspace intact. Cursor lists the machine as offline until you start it again.

​
Before you begin

  • A Sprites organization with Sprites active.
  • A Cursor user API key, created under API keys in the Cursor dashboard. The dashboard verifies the key with Cursor before it builds anything, and never stores it: the key lives only in the worker’s environment on the Sprite.
  • Self-hosted machines enabled for the Cursor account that owns the key: open Cloud Agents settings in the Cursor dashboard and turn on Enable Self-hosted Machines.
The Cursor account that owns the key must be on the current privacy setting, not legacy privacy mode. Legacy privacy mode blocks Cloud Agents, and a self-hosted worker is still a Cloud Agent from Cursor’s side: it connects and reports it is running, but Cursor never lists it. Check under Settings › Privacy in Cursor.

​
Create a Cursor machine

  1. In the Fly.io dashboard, open your organization’s Sprites page and choose the Integrations tab.
  2. Open Cursor Cloud Agents.
  3. Paste your Cursor API key and give the machine a name. That name is what Cursor shows under My Machines; the Sprite is named cursor-<name>.
  4. Check Computer use if the agent should have a desktop and a browser. See Computer use for what that adds.
  5. Click Create Cursor machine.
The Cursor Cloud Agents page in the Sprites dashboard, with the Create a Cursor machine form and the What happens steps
The dashboard creates the Sprite, installs the worker service, starts it, and waits for Cursor to accept the machine. It takes about a minute, or a few minutes with computer use. When it is done, the machine appears in the Cursor machines table below the form.

​
Use it in Cursor

Each row in the table has Open in Cursor, which opens Cursor’s agents page with that machine selected. Or start a Cloud Agent in Cursor and pick the machine under My Machines. Either way, the agent’s tool calls now run in the Sprite, and whatever repository the task names is cloned into ~/workspace on it. The machine keeps its workspace between sessions. A follow-up on the same machine finds the files where the last agent left them.
A Cursor Cloud Agent session on a Sprites machine, answering a question about the Sprite it runs in

​
Manage machines

The table shows one of three states for each machine:
  • Start runs the worker service, waking the Sprite if it was paused. The machine is back in Cursor within a few seconds, with the same worker id as before.
  • Stop stops the worker. Cursor lists the machine as offline at once, and the Sprite pauses on its own about half a minute later.
  • Delete destroys the Sprite, including the workspace. You type the Sprite’s name to confirm.
A worker that no agent uses for 10 minutes stops by itself, exactly as if you had pressed Stop.

​
Computer use

With Computer use checked, the dashboard installs an Xfce desktop, Google Chrome, and Cursor’s computer use support on the Sprite, so the agent can click, type, and take screenshots. Setup takes a few minutes longer. Ask the agent to take a screenshot to confirm the desktop is up. Two details are handled for you. Cursor’s shell tool kills a command’s whole process group when the command returns, so a browser started as a normal background job dies at once; a wrapper in front of google-chrome always starts it detached and skips the first-run and crash-restore dialogs that would otherwise hide the browser window. And a rule written to ~/.cursor/rules on the Sprite explains the same to the agent for any other GUI program. Edit that file if your desktop needs other instructions.
Cursor’s --share-desktop option lets people watch the agent’s desktop, but with the current Cursor CLI it puts the agent’s shell and its screenshot tool on different displays, so the agent sees an empty desktop and loops. The dashboard runs computer use without desktop sharing.

​
Network access

A worker needs outbound HTTPS to api2.cursor.sh and api2direct.cursor.sh, plus cloud-agent-artifacts.s3.us-east-1.amazonaws.com for artifact uploads. The default Sprite network policy allows all of these. If you restrict egress, keep those hosts and whatever git hosts, package registries, and internal services your agents need.

​
Troubleshooting

Cursor: Self-Hosted Machines

Cursor’s reference for My Machines and self-hosted workers

Services

Supervised long-running processes inside a Sprite

Keeping a Sprite running

The Tasks API hold the worker uses while it is connected

Lifecycle and Persistence

How a Sprite pauses, wakes, and keeps its filesystem