Agents
Self-Hosted Machines for Cloud Agents
Self-Hosted Machines moves Cloud Agent tool execution onto a machine you manage. Cursor still runs the agent loop, inference, and planning, while your worker, started with the Cursor CLI, performs file edits, terminal commands, computer-use tools, and local MCP servers. The worker connects outbound over HTTPS, so no inbound ports, public IPs, or VPN tunnels are required. Team Pools need an Enterprise plan.
On this page
When should a team run Cloud Agents on its own machines?
Cursor treats Self-Hosted Machines as the exception to its default. Managed Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. are the recommended path for most teams and the fastest way to get started, and self-hosting is for the cases where Cursor's managed cloud cannot meet a constraint. The page names three of them.
- Strict network requirements: code or services cannot be reached from outside your network. For private source control or package registries, Cursor says to start with managed Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. and private connectivity (AWS PrivateLinkAn AWS connection Cursor uses for private Git provider and repository-origin traffic; it does not cover model-provider traffic. Press Enter for the full definition. or Cloudflare Tunnel).
- Custom hardware: GPU machines, or Macs for iOS development, on a machine you already run or a VM from a partner host such as AWS Lambda, Cloudflare, Namespace, Modal, Daytona, E2B, Vercel, Tensorlake, or Superserve.
- Custom images: a different operating system or an existing build pipeline that is difficult to save as a Cloud Agent build.
On the first item, Cursor itself sends private source control and package registries toward managed agents plus private connectivity. The constraint it names is code or services that cannot be reached from outside the network.
Cursor lists what managed Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. already cover. Each agent gets an isolated VM that Cursor provisions and tears down, so there is no worker fleet to size, patch, scale, or keep on call. Network allowlists restrict outbound domains by user, team, or environment. Private connectivity reaches self-hosted GitHub Enterprise Server and GitLab Enterprise, and Tailscale or a similar client reaches services in your VPC. Privacy ModeCursor's setting that guarantees code data is not used for training by Cursor or its model providers, and that an admin can enforce org-wide; data-retention terms are a separate, contractual layer. Press Enter for the full definition. and customer-controlled secrets scoped to the environments you choose are part of it too. If those controls cover your requirements, Cursor's position is that you do not need to own the compute to keep agents inside your security perimeter.
The wider comparison of runtimes lives in choosing a Cloud Agent runtime.
This is covered hands-on in Agent Mode Foundations — 6 short Units, free to read.
Rather do it than read about it? Run 11 interactive Cursor walkthroughs in a simulated editor. Free, no account needed.
What leaves your network when a worker runs?
The full checkout, build cache, and machine-local credentials stay on your machine. During a run the worker sends Cursor the content the agent needs: file contents, terminal output, diffs, screenshots, local MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. results, and routing metadata. If you enable desktop sharing, it also streams the agent desktop.
The worker also uploads screenshots, videos, and log references to Cursor-managed storage so they can appear in pull requests and the dashboard. Cursor's instruction is to keep secrets out of tool output and artifacts.
Privacy ModeCursor's setting that guarantees code data is not used for training by Cursor or its model providers, and that an admin can enforce org-wide; data-retention terms are a separate, contractual layer. Press Enter for the full definition. also applies to Self-Hosted Machines. When it is enabled, code sent from the worker is not used for training by Cursor or model providers.
Network review for a worker is short because everything is outbound HTTPS. The table lists the destinations to allow and the proxy variable.
- Destination
api2.cursor.shandapi2direct.cursor.sh- Used for
- The agent session
- Destination
cloud-agent-artifacts.s3.us-east-1.amazonaws.com- Used for
- Artifact uploads
- Destination
HTTPS_PROXYorhttps_proxy- Used for
- Set in the worker environment if you use a proxy
| Destination | Used for |
|---|---|
api2.cursor.sh and api2direct.cursor.sh | The agent session |
cloud-agent-artifacts.s3.us-east-1.amazonaws.com | Artifact uploads |
HTTPS_PROXY or https_proxy | Set in the worker environment if you use a proxy |
No inbound ports, public IPs, or VPN tunnels are required.
To stop artifacts leaving, block outbound traffic to the artifact bucket on the worker. Only the upload stops. The agent keeps working, including tool calls and results, but its artifacts will not appear in pull requests or the dashboard.
How do workers, team pools and controllers fit together?
Three terms carry the whole model: a worker, a team pool, and a controller. The table gives Cursor's definitions with its own examples.
- Term
- Worker
- What it is
- A machine you own, registered to Cursor with the Cursor CLICursor's command line: the full agent, all modes and models, in the terminal and pipeable into scripts and CI. Press Enter for the full definition., where the agent edits files, runs commands, and accesses code
- Example
- A Linux VM in your AWS account, or a Mac mini on your desk
- Term
- Team Pool
- What it is
- A routing target you select in the Cursor client UI. Chats wait in the pool until a worker claims one, then all activity in that chat goes to that worker
- Example
- A
gpupool served only by machines with GPUs, or aniospool served only by Macs
- Term
- Controller
- What it is
- Code you run that adjusts worker capacity based on demand
- Example
- A request arrives on a pool with no idle workers and the controller starts a machine
| Term | What it is | Example |
|---|---|---|
| Worker | A machine you own, registered to Cursor with the Cursor CLICursor's command line: the full agent, all modes and models, in the terminal and pipeable into scripts and CI. Press Enter for the full definition., where the agent edits files, runs commands, and accesses code | A Linux VM in your AWS account, or a Mac mini on your desk |
| Team Pool | A routing target you select in the Cursor client UI. Chats wait in the pool until a worker claims one, then all activity in that chat goes to that worker | A gpu pool served only by machines with GPUs, or an ios pool served only by Macs |
| Controller | Code you run that adjusts worker capacity based on demand | A request arrives on a pool with no idle workers and the controller starts a machine |
agent worker start is the command that makes a machine a worker. It opens a long-lived outbound HTTPS connection to Cursor's backend, and Cursor sends agent tool calls over that connection. Because the connection starts from your side, Cursor never connects into your network.
Workers come in two configurations. My Machines connects a machine to your own account and suits personal workflows and one-offs, such as a devbox, a spare VM, or a machine with state you do not want to recreate. Team Pools register machines under a pool name, and Cursor routes each new chat to an available machine in the pool. The two differ in concurrency: on My Machines several agents can run on the same machine, while a pool gives each chat one machine to itself.
Pools also bring shared capacity, service account authentication, and centrally managed images. Cursor allows up to 200 workers per user and 1000 per team, and for larger company-wide deployments it asks you to contact sales to discuss scaling.
Cursor lists persistent hosts or containers, run under systemd, launchd, Docker or another process manager, as one deployment pattern. For dynamic capacity there is a built-in worker controller, and the Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. API can start machines when requests arrive. On Kubernetes, the anysphere/k8s-workers template runs agent worker controller --spawn in your cluster and creates one worker Pod per claimed request, or keeps warm Pods with --warm-idle, without a CRD.
Cursor calls its deployment guides, partner guides, and templates reference architectures. You own the worker image, infrastructure, secrets, scaling policy, and production validation.
What happens to a Cloud Agent environment on your own machine?
A self-hosted run uses only the environment's repositories. Pool workers that opt in to Secret sync also get team and user secrets. Every other environment setting applies only to Cursor-hosted Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition., so you recreate it on the machine.
What a worker does with the repositories depends on how it runs. An any-repo pool worker started with --clone-git-repos checks out every repository at the requested branch or commit. A repo-backed pool worker or a My Machines worker uses the checkouts it already has, without switching branches or cloning. Your sessionStart hook receives every repository in the request as repo_urls and repos, so it can clone the ones the worker lacks.
A pool worker started with --sync-dashboard-secrets gets secrets as environment variables once a team admin turns on Secret sync in the Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. dashboard. Those are the team and user secrets available to the run's repositories, plus any envVars passed to Create An Agent. Any-repo pools get only secrets that are not limited to a repository. Environment-scoped secrets and Build Secrets never reach a worker. My Machines workers get no dashboard secrets and use the machine's own credentials.
Everything else maps onto something you run yourself. The pattern is that configuration which lived in the environment moves to the machine, its image, or a hook.
- Environment setting
- Install script and startup commands
- Self-hosted equivalent
- A
sessionStarthook in.cursor/hooks.json,--on-session-starton pool workers, or the worker image
- Environment setting
- Terminals and ports
- Self-hosted equivalent
- A hook or your own process manager
- Environment setting
- Dockerfile, image, snapshot, and user
- Self-hosted equivalent
- The machine or worker image, running as the worker's OS user
- Environment setting
- Builds
- Self-hosted equivalent
- A prepared worker image, or warm workers from the worker controller
- Environment setting
- Network access settings
- Self-hosted equivalent
- The machine's firewall or HTTPS proxy
- Environment setting
- Environment-scoped secrets
- Self-hosted equivalent
- Secrets on the machine, or team and user secrets through Secret sync
- Environment setting
- MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. server limits in
environment.json - Self-hosted equivalent
- Your team's MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. servers, available to every run with no per-environment limit
- Environment setting
.cursor/environment.jsonin the repository- Self-hosted equivalent
.cursor/hooks.jsonin the worker directory
| Environment setting | Self-hosted equivalent |
|---|---|
| Install script and startup commands | A sessionStart hook in .cursor/hooks.json, --on-session-start on pool workers, or the worker image |
| Terminals and ports | A hook or your own process manager |
| Dockerfile, image, snapshot, and user | The machine or worker image, running as the worker's OS user |
| Builds | A prepared worker image, or warm workers from the worker controller |
| Network access settings | The machine's firewall or HTTPS proxy |
| Environment-scoped secrets | Secrets on the machine, or team and user secrets through Secret sync |
MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. server limits in environment.json | Your team's MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. servers, available to every run with no per-environment limit |
.cursor/environment.json in the repository | .cursor/hooks.json in the worker directory |
In the network row, the environment's network access settings apply only to Cursor-hosted Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition., and on a self-hosted machine the machine's firewall or HTTPS proxy takes over.
What does it cost and what does a worker need?
Every runtime option uses the selected model and follows its pricing. Cursor-managed Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. include the execution infrastructure. With Self-Hosted Machines, you also pay for and operate your machines, containers, or cluster.
In other words, self-hosting adds the cost of your own infrastructure on top of the model cost.
Every worker needs the Cursor CLICursor's command line: the full agent, all modes and models, in the terminal and pipeable into scripts and CI. Press Enter for the full definition. and outbound HTTPS access. Install the CLI on each machine, then add the credential for your configuration from the list below.
curl https://cursor.com/install -fsS | bash
- My Machines: a personal credential, either browser login with
agent loginor a personal user API key from Cursor Dashboard → API Keys. - Team Pools: an Enterprise plan and a service account API key exported as
CURSOR_API_KEY. Personal logins and other API key types cannot start pool workers. - Team admin settings: in the Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. dashboard, Allow Self-Hosted Machines lets users opt in and Require Self-Hosted Machines routes every Cloud Agent run to your workers.
- Computer use (optional): a macOS worker with a signed-in desktop session, where the CLI installs the Cursor Computer Use helper app on first start and you grant it Accessibility and Screen Recording. Or a Linux worker with the desktop packages, which creates its own desktop or reuses an existing X11 display.
Chats wait in a pool until a worker claims them. Team Pools need an Enterprise plan, and Cursor points teams that want worker fleets, private connectivity, and rollout help to sales.
Frequently asked questions
Does Self-Hosted Machines run the agent loop on my own hardware?
No. Cursor runs the agent loop, inference, and planning. Your worker performs file edits and terminal commands, and it also runs computer-use tools and local MCP servers. Your team still uses Cloud Agents through the desktop app, cursor.com, and mobile.
Do self-hosted workers need inbound ports or a VPN?
No. Workers need outbound HTTPS access to api2.cursor.sh, api2direct.cursor.sh, and cloud-agent-artifacts.s3.us-east-1.amazonaws.com for artifact uploads. No inbound ports, public IPs, or VPN tunnels are required. If you use a proxy, set HTTPS_PROXY or https_proxy in the worker environment.
Do I need an Enterprise plan for Self-Hosted Machines?
For Team Pools, yes. They need an Enterprise plan and a service account API key, since personal logins and other API key types cannot start pool workers. My Machines needs a personal credential: a browser login with agent login, or a personal user API key from the Cursor Dashboard.
Sources & last verified
- Cursor docs: Self-Hosted Machines
- Cursor docs: Choose where Cloud Agents run
- Cursor docs: My Machines
- Cursor docs: Team Pools
- Cursor docs: Self-Hosted Integrations
- Cursor docs: Computer use and desktop sharing
- Cursor docs: Private connectivity
- Cursor docs: Cloud Agent security and network
Cursor ships frequently. Facts verified against primary sources on October 17, 2026.