Pools

A pool is a named routing target that connects requests with workers. Requests wait in the pool until an available worker claims them. Create separate pools for different execution environments, such as gpu for work that needs GPUs or ios for work that needs a Mac.

See Requirements for the plan, credential, dashboard settings, and machine dependencies pools need.

Register workers to a pool

Register a worker with the Cursor CLI:

export CURSOR_API_KEY="<team service-account API key>"cd /path/to/repo   # or any directory for an any-repo poolagent worker --pool my-pool start

If you supply a new name, the CLI creates the pool. If the pool name already exists, the worker joins the existing pool. If you omit the name, the worker joins the default pool.

Manage pools

Pools are durable. A pool stays registered and selectable after the last worker disconnects, so you can scale to zero and bring capacity back when requests arrive. Manage pools with the Cloud Agents API:

• POST /v0/private-workers/pools registers a pool up front, before any worker connects.
• GET /v0/private-workers/pools lists pools with connected and in-use worker counts.
• DELETE /v0/private-workers/pools soft-deletes a pool. It does not affect machines currently connected to the pool.

Route requests to a pool

You can select a pool in the Cursor app, on cursor.com/agents, or in the Cursor mobile app. Pool names also work in Cloud Agent integrations:

A team admin must enable Enable Self-Hosted Pool before users can request a pool explicitly. When Require Self-Hosted Pool for All Cloud Agents is enabled, Cursor routes Cloud Agent requests to eligible pool workers unless the request targets a specific personal machine.

Pool requests match the pool name and repository. A request for pool=gpu and repo=acme/payments only routes to a connected worker with both labels. GitHub only accepts self-hosted routing requests from trusted repository collaborators.

Pools and repos

Pools come in two repo configurations. A repo-backed pool ties the pool to one repository: Cursor routes repo-scoped requests to it, and workers serve a checkout of that repo. An any-repo pool leaves source control to you.

Repo-backed pools

Use a repo-backed pool when its workers serve specific repositories and you want requests for those repos routed automatically.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/pools" \  -u "$CURSOR_API_KEY:" \  -H "Content-Type: application/json" \  --data '{    "scope": "team",    "poolName": "payments-pool",    "repoOwner": "acme",    "repoName": "payments",    "repoUrl": "https://github.com/acme/payments"  }'

cd /path/to/paymentsagent worker --pool payments-pool start

A repo-backed worker can serve more than one repository. Pass --worker-dir once per repo root. The first root is the worker's assignment identity, and every root with a git remote registers a repo=<owner/repo> routing label:

agent worker --pool app-infra \  --worker-dir "$HOME/repos/app" \  --worker-dir "$HOME/repos/infra" \  start

Requests route on their selected repository and match any worker in the pool serving it.

Any-repo pools

If you prefer to manage source control yourself, create a pool without a repo attached. For these pools, you can add a .cursor/rules file in the directory where you run agent worker start. Use the rules file to teach Cursor which directories and tools are available on those machines.

mkdir -p "$HOME/cursor-sandboxes/default"

agent worker --pool sandbox --worker-dir "$HOME/cursor-sandboxes/default" start

agent worker --pool sandbox --clone-git-repos start

Add routing labels

Labels describe a worker's environment or capabilities. Add labels with repeatable CLI flags:

agent worker \  --pool gpu \  --label team=backend \  --label environment=production \  start

For managed worker images, store labels in a JSON or TOML file:

{  "team": "backend",  "environment": "production",  "capabilities": ["docker", "gpu"]}

Pass the file when the worker starts:

agent worker --pool gpu --labels-file /etc/cursor/labels.json start

Set CURSOR_WORKER_LABELS_FILE instead when your orchestrator injects the path. --label and --labels-file cannot be combined.

Set the pool with --pool, not --label. The --pool flag enables pool assignment and registers the pool=<name> label.

Cursor normally derives repo=<owner/repo> labels from the Git remotes of each --worker-dir. For multi-repo workers, prefer one --worker-dir per checkout. If a checkout does not have a usable Git remote, add its routing label manually by repeating --label repo=<owner/repo> or including repo in a labels file. A manual label controls routing only. The checkout must already exist under an exposed worker directory.

Use hooks and MCP servers

Pool workers run project hooks from .cursor/hooks.json. Enterprise workers also support team hooks and enterprise-managed hooks. See Hooks.

Cursor runs each MCP server based on its transport:

Add and enable personal MCP servers through the MCP dropdown in cursor.com/agents. Team admins configure shared servers under Dashboard -> Integrations & MCP. Bake command-based MCP dependencies into the worker image so every machine in the pool has the same tools.

Scale a pool with a controller

A controller is code you run that adjusts worker capacity based on demand. The Cursor CLI ships with one: agent worker controller takes care of watching the request queue, and you provide a spawn script that starts new machines. We recommend using it. To build your own custom controller instead, see Build your own controller.

The request flow

1. A user selects the pool in the Cursor app, on cursor.com/agents, or in the Cursor mobile app.
2. They type a request and send it.
3. The request enters the request queue for that pool.
4. If the pool has an available worker, that worker claims the request. Cursor routes all follow-up activity in the chat to the claimed worker.

If the pool has no available workers, the request waits in the request queue until a worker becomes available.

Run the built-in controller

agent worker controller handles pool registration, the list-then-watch loop, and claims. You provide a spawn script that boots one worker machine per invocation:

agent worker controller \  --spawn ./spawn.sh \  --api-key "$CURSOR_API_KEY" \  --pool gpu --pool default

Warm pool (keeps five idle workers connected in gpu by pre-spawning unclaimed workers):

agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool gpu --warm-idle 5

agent worker controller --warm-idle keeps process-forked workers via --spawn. It does not patch a Kubernetes WorkerDeployment. On Kubernetes, keep warm size with WorkerDeployment.spec.readyReplicas. See the Kubernetes deployment guide.

The controller runs in one of two modes:

• Claim-then-spawn (default). The controller lists and watches pending requests, claims each one, and runs the spawn script once per claim. The spawn script boots a machine that starts a worker with the claimed worker id, so the request is seated as soon as the machine connects.
• Warm pool (--warm-idle <count>). For keeping a few always-idle workers in each pool. The controller pre-spawns unclaimed workers to hold count idle workers per --pool and never calls claim; Cursor assigns queued requests to the warm workers. Reconciles against GET /v0/private-workers/pools every 60 seconds; the pending-requests SSE stream only accelerates backfill. Run one warm controller per pool: without a claim there is no server-side lease, so concurrent controllers can transiently over-spawn.

The spawn script receives everything it needs as environment variables:

A minimal spawn script boots a machine or container that inherits those variables and starts a worker:

#!/usr/bin/env bashset -euo pipefaildocker run -d \  -e CURSOR_API_KEY \  -e CURSOR_AGENT_WORKER_ID \  -e CURSOR_WORKER_POOL_NAME="$CURSOR_POOL" \  your-worker-image \  agent worker --pool start

Session lifecycle

Once a worker is matched to a request, Cursor forwards all agent tool calls directly to the machine. The connection has an idle timeout that defaults to 1 hour. Configure it as needed:

agent worker --pool my-pool --idle-release-timeout 600 start

--idle-release-timeout (env var CURSOR_WORKER_IDLE_RELEASE_TIMEOUT) is the number of seconds the worker stays connected after a session ends, waiting for follow-up messages. If a follow-up arrives, the timer resets. When the timeout fires, the CLI exits with code 0 so a supervisor can recycle the machine. Pass 0 to disable idle-based release. Releasing a claim is a separate API: it stops preferring that machine for the agent, and does not exit the worker CLI.

Once a worker times out, Cursor marks it as freed. The machine can reset and re-enter the pool. If a user restarts a chat that has disconnected from its machine, the chat reconnects to a fresh machine from the pool. Workspace state from the original machine does not carry over.

Build your own controller

The built-in controller covers most setups. If you need custom logic, for example your own scheduling, quotas, or machine placement, you can build a controller on the same Cloud Agents API. A controller does three things: watch the request queue, claim a request, and start a worker for it.

Monitor the request queue

List the queue once to build your view of pending requests, then follow changes in real time over Server-Sent Events (SSE).

Start with GET /v0/private-workers/pending-requests. Add ?pool=<name> to watch a single pool. Paginate to completion and keep the streamCursor from the response:

curl --request GET \  --url "https://api.cursor.com/v0/private-workers/pending-requests?pool=my-pool&limit=50" \  -u "$CURSOR_API_KEY:"

Then open the event stream with GET /v0/private-workers/pending-requests/stream, passing that streamCursor and the same filters. Keep your view current as events arrive: add requests from created and claimed_offline events, and drop requests when you see claimed or expired:

curl --request GET --no-buffer \  --url "https://api.cursor.com/v0/private-workers/pending-requests/stream?pool=my-pool&cursor=$STREAM_CURSOR" \  --header 'Accept: text/event-stream' \  -u "$CURSOR_API_KEY:"

Cursors expire five minutes after the list that issued them. When the stream returns 410 Gone, list again and reopen the stream from the fresh streamCursor. Better yet, list again every five minutes with some jitter instead of waiting for the 410.

The number of requests in your view is the pool's queue depth. When it grows, add workers. GET /v0/private-workers/summary tells you how many workers are connected and how many are busy, so you can size the response. Treat events as hints and the list as the source of truth: event delivery is best-effort, and each new list corrects any drift. See Watch Pending Pool Requests for the full delivery guarantees and cursor rules.

Claim a request

Reserve a pending request for a specific worker before that worker starts, so two controller replicas never boot two machines for the same request. Call POST /v0/private-workers/claim with the request's id (from the list response or a created event) and the worker id you plan to start:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claim" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "id": "bc-00000000-0000-0000-0000-000000000002",    "workerId": "pw_123"  }'

Start a worker for the claim

When you connect the worker, supply the same worker id.

Environment variable (preferred, because older CLI builds ignore an unknown env var):

export CURSOR_AGENT_WORKER_ID="pw_123"agent worker --pool my-pool start

CLI flag:

agent worker --worker-id pw_123 --pool my-pool start

Release a claim

Use Release A Claim with the same id you passed to claim. That drops the routing preference for this machine so a replacement worker can claim the agent:

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/claims/bc-00000000-0000-0000-0000-000000000002/release" \  -u "$CURSOR_API_KEY:"

A waiting follow-up returns to the pool queue at the next scheduling point. A connected worker finishes its current turn. A second claim while a live claim exists is rejected; release first, then claim a new workerId.

Hibernation

A pool machine does not have to stay online while its agent is idle. After a session ends, the worker waits for follow-ups until its idle timeout fires, and keeping every machine up between turns gets expensive.

The tradeoff is workspace locality. Without hibernation, a follow-up that arrives after the machine released reacquires from the pool: the agent lands on a fresh machine and may spend its first minutes reconstructing the workspace it already had. With hibernation, the machine comes back with its workspace intact and the follow-up resumes where the agent left off.

curl --request POST \  --url "https://api.cursor.com/v0/private-workers/pools" \  -u "$CURSOR_API_KEY:" \  --header 'Content-Type: application/json' \  --data '{    "scope": "team",    "poolName": "gpu",    "workerReadyTimeoutSeconds": 900  }'

export CURSOR_AGENT_WORKER_ID="<claimedWorkerId>"agent worker --pool gpu start

Monitor workers

Start the worker management server:

agent worker --pool gpu --management-addr ":8080" start

It exposes:

The main metrics are:

• cursor_self_hosted_worker_connected
• cursor_self_hosted_worker_session_active
• cursor_self_hosted_worker_last_activity_unix_seconds
• cursor_self_hosted_worker_connect_attempts_total
• cursor_self_hosted_worker_connect_retry_total
• cursor_self_hosted_worker_connect_failures_total
• cursor_self_hosted_worker_session_ends_total

Use GET /v0/private-workers/pools for connected and in-use counts per pool. Use the pending-request queue for demand and autoscaling. The team-wide worker summary is not a substitute for pool-specific demand.

CLI reference

Worker flags go before the subcommand:

agent worker [options] start

Run agent worker --help for the full list, and agent worker debug for a preflight report.

FAQ

Next steps

• Choose where Cloud Agents run: compare managed Cloud Agents, My Machines, and Pools.
• My Machines: connect a personal laptop, devbox, or VM.
• Computer use: let agents drive a desktop and browser on your workers.
• API reference: endpoints for workers, pools, the pending-request queue, and worker tokens.
• Kubernetes deployment guide: operator and Helm chart for pools at scale.