Bring your own machine

Bring your own machine (BYOM) 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 bring their own machine

Bring your own machine 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 host such as AWS, Namespace, Coder, or Cloudflare.
• 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.

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. 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 Pools.

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.
• AWS reference deployments. The self-hosted Cloud Agents cookbook includes EC2, ECS/Fargate, and EKS examples.

Provider-specific deployment examples 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 BYOM, 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

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 Agents lets users opt in, and Require Self-Hosted Agents routes every Cloud Agent run to your workers.

Computer use (optional)

• 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 full setup.

Next steps

• Choose where Cloud Agents run: compare managed Cloud Agents, My Machines, and Pools.
• Quickstart: connect your first worker in a few minutes.
• My Machines: configure personal workers, workspace roots, and local MCP servers.
• Pools: organize workers into pools for your team, and scale worker capacity with a controller.
• 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.