pages/cloud-agent/my-machines.txt

route: /docs/cloud-agent/my-machines
title: My Machines
description: Run Cloud Agents on a machine you already use, like your laptop, devbox, or remote VM.

My Machines
My Machines lets a specific user run Cloud Agent tool calls on a machine they already use: a laptop, devbox, or remote VM. Use it when that machine is the desired execution environment for a repo.
A worker on your machine opens an outbound connection to Cursor. The agent loop runs in Cursor's cloud, but terminal commands, file edits, browser actions, and other tool calls execute on your machine. No inbound ports or firewall changes are required.
Cursor-managed Cloud Agents are the recommended path for most teams, including
teams that need access to private networks. You can use network allowlists,
Tailscale or similar clients, and private connectivity for supported source
control paths without operating your own worker. See Choose where Cloud
Agents run.
Use My Machines when you want to:
Use a devbox or remote workstation that already has your repo and tools
Execute tool calls on one user's machine for a specific repo
Reuse machine-local state that you do not want to recreate in a cloud environment
Try the worker model before building a centrally managed pool
For org-wide worker fleets, see Self-Hosted Pool.
Quickstart
1. Install the CLI
# macOS, Linux, and WSL
curl https://cursor.com/install -fsS | bash
# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex
Confirm the CLI is available:
agent --version
2. Sign in
For a personal machine, browser login is the easiest path:
agent login
3. Start the worker
agent worker start
Keep this process running while you use the machine. By default, a My Machines worker is long-lived: it stays connected until you stop it and can be reused for future Cloud Agent sessions.
4. Run an agent
Go to cursor.com/agents.
The machine should show up in the environment dropdown.
Send a task.
Common options
Name the machine
Use a friendly name when you have multiple machines for the same repo:
agent worker start --name "my-devbox"
Run from a different repo directory
agent worker start --worker-dir /path/to/repo
Use an API key
For shared devboxes or automation, use a service account API key:
agent worker start --api-key "your-api-key"
Use a user-scoped token
For self-managed per-user workers, mint a short-lived user-scoped token with POST /v1/sub-tokens, then start the worker with that token:
agent worker start --auth-token "your-user-scoped-token"
For long-lived workers, read the token from a file:
agent worker start --auth-token-file /var/run/cursor/token
This is useful in Kubernetes because environment variables from Secrets are fixed when the pod starts. Secret volumes update while the pod runs, while mounted token paths can be live updated within the pod giving you the chance to refresh the token while the pod is running.
Trigger this machine from a chat surface
Use worker= or machine= when you want Slack, GitHub, or Linear requests to run on one of your named machines. These are the only trigger options that target My Machines.
Start the machine with --name, then include that name in the request:
In Slack, use @Cursor worker=my-devbox fix the flaky test or @Cursor machine=my-devbox fix the flaky test.
In GitHub, comment @cursoragent worker=my-devbox fix the flaky test or @cursoragent machine=my-devbox fix the flaky test. You must be a trusted repo commenter, and the target machine must belong to the Cursor user linked to your GitHub account.
In Linear, add worker=my-devbox or machine=my-devbox to the issue body. You can also use a parent label named worker or machine with a child label named my-devbox.
How Cursor picks your machine
A worker=<name> request runs on a machine only when all three are true:
The machine belongs to the Cursor user who triggered the request.
The machine's --name matches the requested <name>.
The machine's registered repo matches the trigger's target repo.
The trigger's target repo comes from the surface, not from the machine name:
Slack uses repo= in your message if present, then the channel default repo, your user default repo, then the team default repo.
Linear uses the repo resolved from the issue or project (for example [repo=], issue labels, project labels, or the dashboard default). See Repository selection.
GitHub uses the repo of the issue, pull request, or review comment where @cursoragent was mentioned.
Each machine's registered repo comes from the git remote in the directory where you started the worker. To serve more than one repo, start a worker in each repo's checkout.
When a worker= request can't run
If you have a machine with that name but it's registered for a different repo, Cursor rejects the request rather than running it on the wrong checkout:
worker=<name> is registered on your machine but for a different repository. Start the worker in a checkout of the target repo first.
The error appears as an ephemeral reply in Slack, an agent activity error in Linear, and a @cursoragent reply on GitHub for trusted commenters. The behavior is intentional: a request for repo A should never run on a machine checkout for repo B.
If no machine matches the linked user and target repo, the request fails instead of falling back to another environment. Confirm the machine name, your Cursor account linking, and the worker directory's git remote.
self_hosted, pool=, and repo= on their own don't target My Machines. Use them with Self-Hosted Pool workers. When you pair repo= with worker=, it sets which repo Cursor matches against your machines.
Artifacts
Artifact behavior is identical on self-hosted workers and Cursor-hosted agents. The agent produces the artifact inside the worker and the worker uploads it to Cursor-managed storage over HTTPS. Everything downstream (PR embeds, dashboard previews, notification attachments) is handled by Cursor's backend and doesn't depend on where the worker runs.
Artifacts are on by default. See Capabilities for what they look like in the UI.
To disable artifact uploads, block outbound traffic to cloud-agent-artifacts.s3.us-east-1.amazonaws.com. The agent session keeps working; artifacts produced during the session fail to upload.
Networking
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
If your firewall can only match wildcards, *.s3.us-east-1.amazonaws.com covers the artifact host, but also opens every other bucket in the region. Prefer an exact-host rule when the firewall supports it.
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.
Failure modes
If you block...
Effect
api2.cursor.sh or api2direct.cursor.sh
The worker can't start or continue an agent session.
cloud-agent-artifacts.s3.us-east-1.amazonaws.com
Artifact uploads fail. PR embeds, dashboard previews, and notification attachments that depend on artifacts are missing. The agent session and other tool calls keep working.
An outbound host a specific tool or integration needs
Only that tool or integration fails. The agent continues.
MCP servers
MCP servers are routed by transport type:
Transport
Runs on
Use case
Command (stdio)
Your machine
The MCP process starts on your machine and can reach private networks, internal APIs, and local services.
HTTP / SSE (url)
Cursor backend
Cursor handles OAuth, session caching, and auth for HTTP-based MCP servers.
If your MCP server needs to reach endpoints on your private network, use the command (stdio) transport. The process runs directly on your machine and shares its network. For HTTP-based MCP servers, Cursor manages the connection from its backend.
Troubleshooting
Run a preflight debug report:
agent worker start --debug
This checks authentication, privacy routing, repo labels, and whether Cursor can see matching workers.
Related
Self-Hosted Pool
Cloud Agent security and net
…