Self-Hosted Machines

Self-Hosted Machines moves Cloud Agent tool execution to a machine you manage. Your team still uses Cloud Agents through the desktop app, cursor.com, and mobile. Cursor runs the agent loop, inference, and planning. Your worker performs file edits and terminal commands. It also runs computer-use tools and local MCP servers.

Who should use Self-Hosted Machines

Use Self-Hosted Machines when Cursor's managed cloud can't meet your constraints:

• You have strict network requirements, and code or services can't be reached from outside your network. For private source control or package registries, start with managed Cloud Agents and private connectivity (AWS PrivateLink or Cloudflare Tunnel).
• You have custom hardware, such as GPU machines or Macs for iOS development. Use a machine you already run, or a VM from a partner host such as AWS Lambda, Cloudflare, Namespace, Modal, Daytona, E2B, or Vercel.
• You have custom images, such as a different operating system or an existing build pipeline, that are difficult to save as a Cloud Agent build.

Prefer managed Cloud Agents when

You don't need to own the compute to keep agents inside your security perimeter. Stay on Cursor-managed Cloud Agents when these controls cover your requirements:

• Isolated VMs per agent, provisioned and torn down by Cursor, with no worker fleet to size, patch, scale, or keep on call.
• Network allowlists that restrict outbound domains by user, team, or environment.
• Private connectivity over AWS PrivateLink or Cloudflare Tunnel to self-hosted GitHub Enterprise Server, GitLab Enterprise, and private source control APIs, plus Tailscale or a similar client for services in your VPC.
• Privacy Mode and customer-controlled secrets scoped to the environments you choose. See Cloud Agent security and network for the full model.

What leaves your network

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, such as file contents, terminal output, diffs, screenshots, local MCP results, and routing metadata. If you enable desktop sharing, it also streams the agent desktop.

The worker uploads Cloud Agent artifacts, such as screenshots, videos, and log references, to Cursor-managed storage so they can appear in pull requests and the dashboard. Keep secrets out of tool output and artifacts.

Workers need outbound HTTPS access to:

• api2.cursor.sh and api2direct.cursor.sh for the agent session
• 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.

To disable artifact uploads, block outbound traffic to cloud-agent-artifacts.s3.us-east-1.amazonaws.com on the worker. This only prevents artifacts from uploading. The agent continues to work, including tool calls and results, but its artifacts won't appear in pull requests or the dashboard.

How it works

Use the Cursor CLI to start a worker on your machine. agent worker start opens a long-lived outbound HTTPS connection to Cursor's backend, and Cursor sends agent tool calls over that connection. Cursor never connects into your network: the outbound connection from your machine to Cursor is all that's required.

Workers come in two configurations:

1. My Machines. Best for personal workflows and one-offs: your devbox, a spare VM, or a machine with state you don't want to recreate. Connect a machine to your account. Multiple agents can run on the same machine. See My Machines.
2. Team Pools. Best for teams and enterprises: shared capacity, service account authentication, and centrally managed images. Register machines under a pool name, and Cursor routes each new chat to an available machine in the pool, one agent per machine. Run a controller to scale the pool up and down. See Team Pools.

To run Team Pool workers on a third-party VM or sandbox, see Integrations.

Supported deployment patterns

Run a worker anywhere you can install the Cursor CLI and its dependencies:

• Personal machines. Connect a laptop, devbox, Mac, or remote VM through My Machines.
• Persistent hosts or containers. Run one or more pool workers under systemd, launchd, Docker, or another process manager.
• Dynamic infrastructure. Use the built-in worker controller or the Cloud Agents API to start machines when requests arrive.
• Kubernetes. Follow the Kubernetes guide to run pool workers with the Cursor operator and Helm chart.
• Partner hosts and templates. Run pool workers on AWS Lambda, Cloudflare, Namespace, Modal, Daytona, E2B, Vercel, or Coder with partner guides, or clone a Cursor reference template for AWS Lambda MicroVMs, Cloudflare Containers, or Kubernetes. See Integrations.

Deployment guides, partner guides, and templates are reference architectures. You own the worker image, infrastructure, secrets, scaling policy, and production validation.

Cost

Every runtime option uses the selected model and follows its pricing. Cursor-managed Cloud Agents include the execution infrastructure. With Self-Hosted Machines, you also pay for and operate your machines, containers, or cluster.

Requirements

Every worker needs the Cursor CLI and outbound HTTPS access. Install the CLI on each machine:

curl https://cursor.com/install -fsS | bash

My Machines

• A personal credential: browser login, or a personal user API key from Cursor Dashboard → API Keys.

  agent login

Team Pools

• A Cursor Enterprise plan.

• A service account API key for worker authentication. Personal logins and other API key types can't start pool workers.

  export CURSOR_API_KEY="<team service-account API key>"

• Self-hosted settings configured by a team admin in the Cloud Agents 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. The CLI installs the Cursor Computer Use helper app on first start; grant it Accessibility and Screen Recording in System Settings.

• Or a Linux worker with the desktop packages. The worker creates its own desktop or reuses an existing X11 display:

  sudo apt-get install -y --no-install-recommends \  dbus-x11 ffmpeg tigervnc-standalone-server \  x11-utils x11-xserver-utils xdotool xfce4

  See Computer use and desktop sharing for the macOS permission steps and the full Linux setup.

Next steps

• Choose where Cloud Agents run: compare managed Cloud Agents, My Machines, and Team Pools.
• My Machines: connect your first worker in a few minutes, then configure personal workers, workspace roots, and local MCP servers.
• Team Pools: organize workers into team pools, and scale worker capacity with a controller.
• Kubernetes: deploy pool workers with the operator and Helm chart.
• Integrations: partner guides for AWS Lambda, Cloudflare, Namespace, Modal, Daytona, E2B, Vercel, and Coder, and reference templates for AWS Lambda MicroVMs, Cloudflare Containers, and Kubernetes.
• Computer use: let agents drive a desktop and browser on your workers.
• API reference: endpoints for workers, pools, the pending-request queue (list, SSE watch, claim, and release), and worker tokens.
• Self-Hosted Machines: short answers for setup, Team Pools, integrations, and troubleshooting.