Cloud Agents on My Machines: Run Agent Tools on Hardware You Manage

My Machines lets a specific user run Cloud Agent tool calls on a machine they already use, such as a laptop, a devbox, or a remote VM. A worker on that machine opens an outbound connection to Cursor. The agent loop runs in Cursor's cloud, while terminal commands, file edits, browser actions, and other tool calls execute on your hardware. Because the connection only goes outbound, there are no inbound ports to open and no firewall changes to request.

Cursor lists four situations where the machine itself is the right execution environment for a repo.

• You have a devbox or remote workstation that already has your repo and tools.
• You want tool calls to execute on one user's machine for a specific repo.
• The machine holds local state that you do not want to recreate in a cloud environment.
• You want to try the worker model before building a centrally managed pool.

For org-wide worker fleets, Cursor points to Team Pools.

Cursor also says that 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. are the recommended path for most teams, including teams that need private networks. Network allowlists, Tailscale or similar clients, and private connectivity for supported source control paths cover a lot of that ground without anyone operating a worker. The runtime comparison lays out all three options side by side.

Setup is four steps.

1. 1Install the CLI, then confirm it with agent --version.
2. 2Sign in with agent login. For a personal machine, browser login is the easiest path.
3. 3Start the worker with agent worker start and leave the process running.
4. 4Open cursor.com/agents, pick the machine under My Machines in the menu that sets where the agent runs, and send a task.

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

irm 'https://cursor.com/install?win32=true' | iex

Cursor tells you to keep the worker process running while you use the machine. By default it is long-lived: it stays connected until you stop it and can be reused for future Cloud Agent sessions, so one start covers many tasks.

If the machine does not show up in the picker, the troubleshooting section at the end of this page walks through the usual causes in order.

Most options are flags on the worker command. Two of them, --identity-socket and --computer-use, go before start rather than after it. The table below lists each option and what it changes.

The credential rule is strict. My Machines workers need a personal credential: browser login, a personal user API key, or a user-scoped token. Service account API keys only start pool workers (--pool), and team Admin API keys and organization API keys cannot start workers at all. So a shared devbox that you want to run under a service account is pool territory.

The token-file route suits long-lived workers. Environment variables from Kubernetes Secrets are fixed when the pod starts, whereas secret volumes update while the pod runs. A mounted token path can therefore be refreshed without restarting the pod.

A few details about scope are easy to miss. With several --worker-dir roots, each root that has a Git remote gets routing metadata, which is how Cursor matches a request to the right checkout. A Cloud Agent environment on your machine sets only which repositories a run uses: the machine keeps its own tools, credentials, and network, and gets no dashboard secrets. And an agent started with POST /v1/agents and env.type: "machine" gets exactly one repo in repos. For several repos in one agent, Cursor points to an any-repo pool instead.

On macOS, the first start with --computer-use installs the Cursor Computer Use helper app. You grant it Accessibility and Screen Recording in System Settings, under Privacy & Security, then test with a task that takes a screenshot. Linux needs the desktop packages installed first. Cursor keeps the permission steps and display options in its computer use guide.

Put worker= or machine= plus the machine's --name into the request. Those are the only trigger options that target My Machines. The list below shows how each surface takes it.

• Slack: @Cursor worker=my-devbox fix the flaky test, or machine=my-devbox in the same position.
• GitHub: comment @cursoragent worker=my-devbox fix the flaky test. You must be a trusted repo commenter, and the machine must belong to the Cursor user linked to your GitHub account.
• Linear: mention @Cursor in a comment to start the run. The worker= text in the issue body, or a parent label named worker or machine with a child label named for your machine, is honored only for that same comment trigger. Assigning or delegating the issue ignores both.

A worker=my-devbox request runs on that machine only when it also holds a checkout of the target repo, because Cursor checks three conditions before it picks a machine.

1. 1The machine belongs to the Cursor user who triggered the request.
2. 2The machine's --name matches the requested name.
3. 3The machine's registered repo matches the trigger's target repo.

The target repo comes from the surface, never from the machine name. A machine's registered repos come from the Git remotes of its worker directories, so serving more than one repo from one machine means passing --worker-dir once per checkout, or starting a worker in each repo's checkout.

When a machine has the right name but is registered for a different repository, Cursor rejects the request instead of running it on the wrong checkout. Cursor says that behavior is intentional: a request for repo A should never run on a machine checkout for repo B. The error shows up as an ephemeral reply in Slack, an agent activity error in Linear, and a @cursoragent reply on GitHub for trusted commenters. If no machine matches the linked user and the target repo, the request fails and does not fall back to another environment, so check the machine name, the account linking, and the worker directory's Git remote.

Workers need outbound HTTPS to three hosts: api2.cursor.sh and api2direct.cursor.sh for the agent session, downloads.cursor.com for CLI updates and the first-time Cursor Computer Use install on macOS, and cloud-agent-artifacts.s3.us-east-1.amazonaws.com for artifact uploads. The table shows what breaks when each one is blocked.

No inbound ports, public IPs, or VPN tunnels are required. Behind a proxy, set HTTPS_PROXY or https_proxy in the worker's environment. 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, so prefer an exact-host rule when you can write one.

Artifacts are on by default and behave the same on self-hosted workers as on Cursor-hosted agents: the agent produces the artifact inside the worker, and the worker uploads it to Cursor-managed storage over HTTPS. Blocking the artifact host is also the documented way to turn uploads off. Hooks work the same way across Self-Hosted Machines workers. A My Machines worker runs the command-based hooks from .cursor/hooks.json in the workspace you start it from, and on Enterprise it also runs team hooks and enterprise-managed hooks.

A stdio server runs on your machine and shares its network, while an HTTP server is handled by Cursor's backend.

When something looks wrong, run agent worker debug first. It checks authentication, privacy routing, repo labels, and whether Cursor can see matching workers, and agent worker start --debug prints the same diagnostics before the worker starts. If the machine is missing from the picker, work through these in order.

• Confirm the worker process is still running.
• Confirm the Cursor app and the CLI use the same account.
• Check that the worker directory has the expected Git remote.
• Check outbound access to the hosts in the table above.

Computer use on a Mac has one extra catch. The debug report confirms whether Cursor Computer Use is installed but not whether its permissions were granted, so a green report can still sit next to a failing screenshot task. Grant Accessibility and Screen Recording, then retry.