Cursor Cloud Agents

Run Cursor Cloud Agents in isolated Vercel Sandbox microVMs. Cursor handles the agent loop and model inference, while each Sandbox provides the environment where the agent clones code, runs commands, edits files, and executes tests.

This page covers what the integration needs, how the pieces fit together, and where each part lives in the reference implementation. For the complete source, follow Run Cursor Cloud Agents on Vercel Sandbox.

One person sets up the integration for the team. After that, team members only select the pool when they start an agent.

• A Cursor Enterprise plan
• Allow Self-Hosted Machines turned on by a Cursor team administrator in the Cloud Agents dashboard, so users can opt in to self-hosted runs
• An agent-scoped team service account API key created by a Cursor team administrator
• A team-level Cursor GitHub integration with the target repositories authorized
• A Vercel account with Sandbox access
• Node.js 22 or later and the Vercel CLI

The worker snapshot needs the Cursor Agent CLI, git on PATH, and the workspace directory you pass to --worker-dir. The Cursor CLI requires that directory to exist before the worker starts.

A Vercel Function starts a durable Workflow that acts as the pool's controller. The controller watches the Cursor Team Pool for pending requests. For each one it creates a Sandbox from a prebuilt snapshot, starts a Cursor worker inside it, and stops the Sandbox when the agent finishes. The worker token Cursor issues for each request sets the ceiling on how long a session runs, and the controller's polling cadence sets how quickly an idle pool responds.

The controller mints a user-scoped worker token for each request. That token expires after one hour and cannot refresh itself, so it (not the plan limit) sets how long an uninterrupted session can run.

The maximum session duration is 45 minutes on Hobby and 24 hours on Pro and Enterprise. The 45-minute timeout in the reference implementation fits inside both the Hobby limit and the token lifetime. To run longer than an hour on Pro or Enterprise, mint a new token with the service account API key when you need to refresh a running worker. The guide's Production considerations cover how the reference implementation delivers the refreshed token to the worker.

1. Register a Cursor Team Pool with no workers attached. Users can select the pool while no Sandbox compute is running.
2. The parent Workflow polls the pending-request queue and claims each request with a deterministic worker ID.
3. The parent starts a child Workflow for every claimed request.
4. The child retrieves or creates a named Sandbox from a snapshot with the Cursor Agent CLI preinstalled, then starts the request-scoped worker.
5. The child monitors the agent and stops the Sandbox when the agent becomes idle or reaches its timeout.

The Team Pool stays registered when it has no workers. The controller creates capacity only after a request arrives, so the pool scales to zero.

Scaling to zero costs the first user of an idle pool some waiting time. A request that arrives right after the controller backs off to its five-minute interval waits up to five minutes for the next poll, plus the time to create the Sandbox and connect the worker. Shorten the idle interval when that wait matters more than the compute it saves.

Run Cursor Cloud Agents on Vercel Sandbox has the complete code for each file in the reference implementation and walks through the setup in order. The sections below summarize what each stage does, the limits and defaults that shape it, and where it lives in the guide.

Follow the guide's Getting started in this order:

1. Enable Self-Hosted Machines and create the agent-scoped service account API key.
2. Create and link the Vercel project, then store the key as CURSOR_SERVICE_ACCOUNT_API_KEY. See Set up the project.
3. Build a Sandbox snapshot with the Cursor Agent CLI installed. See Build the worker snapshot.
4. Register the vercel-sandbox Team Pool with no workers attached. See Register a scale-to-zero Team Pool.
5. Deploy the controller and start its durable Workflow. See Expose the controller endpoint.

The service account API key stays in Vercel Functions and Workflow. The controller uses it to inspect and claim work and to mint worker tokens. Only the short-lived worker token enters the Sandbox.

The controller is the parent Workflow, which the guide builds in Run the discovery workflow. It polls the Team Pool for pending requests and adjusts how often based on what it finds: every five seconds while it is dispatching work, every minute once it goes idle, and every five minutes after five empty checks in a row. Workflow sleeps do not consume compute while the controller is suspended.

A single Workflow run is capped at 10,000 steps and 25,000 events, so the controller does not run as one endless loop. It polls for a fixed number of cycles, then exits, and a cron job starts the next run. Together they behave like one controller that never stops.

Only one controller runs per pool at a time. If a second one starts, it exits right away instead of competing for requests.

For each claim, the child Workflow mints a worker token for the requesting Cursor user, creates the request's named Sandbox from the worker snapshot with Sandbox.getOrCreate(), writes the token to a file with mode 0600, and starts the Cursor worker as a detached process. The reference implementation uses persistent: false and a 45-minute timeout. See Provision a worker sandbox for the source.

The worker command takes these options and environment variables:

Each Cursor request gets one Sandbox, named after the request, so a Workflow retry reuses the same Sandbox instead of creating a second one. Sandbox.getOrCreate() returns that existing Sandbox as it was first created and ignores any new settings you pass.

After the controller is running, team members open Cursor's Cloud Agents interface and select vercel-sandbox for the run. To start the run through the Cloud Agents API instead, see Start an agent on the team pool for the request body.

For cleanup, network access, capacity limits, and token refresh in production, see Production considerations.