pages/cloud-agent/private-workers.txt

route: /docs/cloud-agent/private-workers
title: Private Cloud Workers
description: Run Cloud Agents in your own infrastructure with Private Cloud Workers.

Private Cloud Workers
Deprecated
This page is no longer maintained. These docs have moved to Self-Hosted
Pool.
Run Cloud Agents in your own infrastructure.
Private Cloud Workers are in closed beta. Contact Cursor for access.
Overview
Private cloud workers let you run Cloud Agents within your own environments. This is useful for two reasons:
Your codebase stays in your environment. Only the chunks of files the model reads leave your network.
You can use existing machines you already have set up in the cloud. This reduces setup work (build caches, private dependencies), and lets you use controls from your own environment.
Architecture
In all Cloud Agents, the Agent Loop (maintains state, calls inference) is separated from the process that executes tool calls (terminal commands, file edits). With Private Cloud Workers, the tool-execution process runs in your environment.
Stays in your network
Full repo on disk. Secrets and credentials. Build caches and artifacts. Private registries and internal APIs.
Crosses to Cursor
Tool results (stdout, diffs, file reads). Worker metadata for routing. Selected prompt context for inference. Real-time progress streamed to the Cursor UI.
Running agent worker start opens a long-lived outbound connection to Cursor's cloud; no inbound ports or ingress rules are required. The agent loop sends tool calls over this connection, and your worker executes them against local tools (terminal, filesystem, browser). Each cloud agent instance gets its own dedicated worker.
Forward Return Inference (LLM) loop
Example
A step-by-step walkthrough showing what runs where (e.g. "Fix the flaky payment test"). The agent loop handles planning and inference; tool calls run on your worker.
1
User sends the prompt from cursor.com/agents.
2
The agent loop calls Inference (LLM) with the prompt + relevant file context. Inference (LLM) responds: "read tests/payment.test.ts, then run the test suite."
3
The agent loop sends a "read file" tool call to your worker through Cursor's network. Your worker reads tests/payment.test.ts from disk and sends it back.
The file never leaves your network. Only the chunk Inference (LLM) needs is sent for inference. A regular Cloud Agent would need a full clone on Cursor's VMs.
4
Inference (LLM) generates a fix and calls "apply edit". The worker patches the file on your disk.
5
Inference (LLM) calls "run terminal command": npm test --filter payment. Your worker runs this inside your network. It hits your private npm registry, your internal test database, your build cache.
A regular Cloud Agent runs in Cursor's cloud. If your private registry, internal DB, or build cache are only reachable inside your network, use a private worker to access them directly.
6
Tests pass. Inference (LLM) decides to commit, push, and create a PR (generates the tool calls), but the actual git commands execute on the worker. The diff, commit output, and PR URL stream back to the Cursor UI in real-time.
Git credentials and push access stay on your machine. No need to share tokens with Cursor's infrastructure.
Test locally (quick start, 5 min)
Prerequisites
Cursor team plan — Private Workers are a team feature.
A git repo — The worker directory must be a git repo with a remote.origin.url configured.
Feature flag access — Contact Cursor to enable Private Workers for your team.
Outbound HTTPS — Allow outbound HTTPS (port 443) to:
Cursor API for auth (default endpoint is https://api2.cursor.sh and https://api2direct.cursor.sh)
Cursor downloads for the CLI installer (https://downloads.cursor.com)
If you use a proxy, set HTTPS_PROXY or https_proxy. The bridge client will use it for outbound connections.
Run this on any machine with the repo cloned; your laptop is fine.
Enable Private Workers in the dashboard
Before you install the CLI or start a worker, a team admin must turn on Private Workers for the organization on the Cloud Agents dashboard.
Install the CLI
Install the agent CLI using the default installer or a custom URL (includes lab channel to get fast releases):
macOS / LinuxCustom install URL
curl -fsSL "https://www.cursor.com/install?channel=lab" | bash
If your organization has a custom install URL from Cursor, append ?channel=lab:
curl -fsSL "https://your-custom-url.example.com/install?channel=lab" | bash
Ensure ~/.local/bin is on your PATH so the agent command is available. See the CLI docs for more info.
Authenticate
Private workers support two auth methods. Pool workers require a service account API key. CLI login only works for non-pool testing.
1. Existing CLI login (for testing)
agent login
Opens a browser window. After you authenticate, the CLI stores a token locally. Best for one-off testing on your laptop.
If CURSOR_API_KEY is set, it takes precedence over CLI login. Unset it before relying on CLI login:
unset CURSOR_API_KEY
2. Service account API key (required for pool workers)
Create a service account API key via the service accounts docs and pass it via flag or environment variable. Pool workers reject other API key types.
agent worker start --api-key "your-service-account-api-key" --worker-dir /path/to/repo
In Kubernetes, store the key in a Secret and reference it as an env var (see Deploying).
The same service account API key works for the fleet management API. Pass it via Basic auth (-u "$CURSOR_API_KEY:") or Bearer token.
Start a worker
Navigate to your repo and start the worker:
cd /path/to/your/repo
agent worker start
Or pass the path explicitly:
agent worker start --worker-dir /path/to/your/repo
To register the worker for pool assignment, use --pool with a service account API key:
agent worker start --api-key "your-service-account-api-key" --worker-dir /path/to/your/repo --pool
You should see the worker appear in the Private Cloud Workers section of the Cloud Agents dashboard.
Monitor workers in the dashboard
After your workers connect, open the Private Workers Dashboard to monitor and manage your fleet. The dashboard shows how many workers are connected, which workers are in use, which workers are idle and ready for new agents, and which repo, workspace, labels, and active agent are attached to each worker.
Team admins can also use the Require Private Workers for All Cloud Agents setting in the dashboard to require team members to use private workers instead of Cursor's default cloud infrastructure.
Who can see idle team workers
Admins can see idle team-scoped private workers and overall team capacity.
Members do not see idle team-scoped workers in the dashboard by default.
If a team-scoped worker is already assigned to one of a member's active cloud agent sessions, that member can still see the assigned worker for that session.
Send a task to your worker
Go to cursor.com/agents.
Select the repo that matches your worker's directory from the dropdown.
Check "Use private worker" above the input box.
Send a task, e.g., "Fix the flaky payment test in tests/payment.test.ts"
The worker directory must be a git repo with a remote.origin.url configured. The CLI reads this URL during startup and will exit if it's missing. Each worker supports a single repo.
Deploying
After testing locally, the next step is running workers on machines that are provisioned and managed automatically.
The designs below are self-managed patterns for the current beta. A managed orchestration layer (Helm chart + Kubernetes operator) is on the roadmap.
A production deployment has three parts: labels to describe workers, a scaling strategy to create workers when capacity runs low, and an idle release timeout to recycle machines after sessions end.
Labels
Workers can provide as many label keys as needed, and keys do not need to be unique. Labels can be passed as command-line arguments, or via a JSON or TOML file. The file path can be passed via command-line arguments or via CURSOR_WORKER_LABELS_FILE.
…