How to enable computer use on Cursor self-hosted Cloud Agent workers

Self-hosted Cloud Agent workers can click, type, take screenshots, and drive applications with a UI on a Mac or Linux machine you run. If Chrome or Chromium is installed, they can drive a browser too. That works for both My Machines and Team Pools. Computer use is an explicit opt-in: the server never enables it.

Desktop sharing is a separate, Linux-only opt-in. Authorized viewers watch or take control of an isolated agent desktop from Cursor. Cursor’s self-hosted machines notes confirm the same picture: with the right desktop packages, an agent can click, type, take screenshots, and drive the browser, and you can watch its desktop or take control from Cursor.

Install or update to the latest Cursor CLI first:

agent update

You can also reinstall using Cursor’s Install the CLI steps.

Put --computer-use before start

Worker flags go before start:

agent worker --computer-use start

Pool workers take the same flag:

agent worker --pool gpu --computer-use start

What happens next depends on the operating system. On macOS, the worker drives the signed-in desktop through a helper app. On Linux, it uses an X11 display and needs desktop packages installed first.

macOS: Cursor Computer Use plus two privacy grants

On macOS, computer use runs through Cursor Computer Use, a small helper the CLI manages. It clicks, types, and captures the screen of the desktop session the worker runs in. The Cursor desktop app is not required on the worker. --display and virtual displays are Linux only. The worker uses the login GUI session of the macOS user that runs it.

The first agent worker --computer-use start on a Mac downloads Cursor Computer Use from downloads.cursor.com and installs it as ~/.cursor/cursor-computer-use/Cursor Computer Use.app when it is missing. One app identity: bundle identifier co.anysphere.cursor-computer-use, signed with Apple Team ID DCNK4UB866. That is a different app from Cursor Agent Helper (co.anysphere.cursor.agent-helper), which --share-desktop uses.

Sign in as the user that will run the worker, then start it:

agent worker --computer-use --name "build-mac-01" start

For a pool worker, add --pool. The first start installs the helper if it is missing, then macOS prompts for permissions.

Open System Settings → Privacy & Security. Under Accessibility, turn on Cursor Computer Use. Under Screen & System Audio Recording (called Screen Recording on older macOS versions), turn on Cursor Computer Use. Grant both to Cursor Computer Use, not Terminal, your shell, the Cursor app, or Cursor Agent Helper. Permissions on those other apps do not carry over. If macOS asks you to quit and reopen after Screen Recording, stop and restart the worker.

The worker does not check or request these permissions. Until you grant them, clicks and screenshots fail.

Keep a signed-in GUI session. On machines that reboot unattended, turn on automatic login for the worker’s user and keep the display awake in System Settings → Lock Screen and Energy. Install and update Cursor Computer Use only through agent worker --computer-use start. Do not copy, re-sign, or rebuild the app; a changed signing identity makes macOS treat it as a new app and your grants stop applying. If your MDM or imaging process already places the helper on the machine, set CUA_SERVICE_APP in the environment of the agent worker process to the path of the .app bundle so the worker skips the download.

macOS 15 (Sequoia) and later periodically ask the logged-in user to re-confirm Screen Recording. If screenshots stop on a long-running worker, look for a pending “Allow For One Month” prompt in the GUI session, approve it, then run agent worker debug again.

Do not script around the prompts. Editing the macOS privacy database or disabling System Integrity Protection is unsupported. Use System Settings or an MDM Privacy Preferences Policy Control (PPPC) profile. A profile can allow Accessibility silently on most macOS versions (Apple deprecates silent allow starting with macOS 26.2). A profile cannot allow Screen Recording; it can set AllowStandardUserToSetSystemService for co.anysphere.cursor-computer-use under the ScreenCapture service so a standard user can approve it without an administrator password. Read the code requirement from the app the CLI installed:

codesign -d -r - ~/.cursor/cursor-computer-use/Cursor\ Computer\ Use.app

For a fleet, grant once on a template Mac as the worker’s user, prove a screenshot-and-click task works, then snapshot. Re-grant if the helper’s signing identity changes, the worker runs as a different macOS user, or you upgrade the template to a new macOS major version.

Linux: desktop packages and an X11 display

On Linux, computer use uses an X11 display. The worker reuses a display you already run, or creates its own. Cursor does not install system packages for you:

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

xdotool, ffmpeg, and the X11 utilities are always required. tigervnc-standalone-server and xfce4 are needed when the worker creates a desktop itself: the managed display for computer use on headless machines, and the isolated desktop for desktop sharing. Install Chrome or Chromium (optional, recommended) for browser computer use. For pools, bake the packages into your worker image.

The worker resolves the display in this order:

1. --display <display> — require an existing X11 display, for example :0. If the display is not reachable, worker start fails instead of falling back.
2. Inherited DISPLAY — without --display, the worker reuses a reachable DISPLAY from its environment. If it is not reachable, the worker falls back to a managed desktop.
3. Managed desktop — with no display configured, the worker starts its own TigerVNC desktop running an Xfce session. This is the default on headless machines.

# Reuse a desktop you already run
agent worker --computer-use --display :0 start

# Let the worker create a managed desktop (headless machines)
agent worker --computer-use start

Desktop sharing is Linux-only

Desktop sharing is separate from computer use. To let authorized viewers watch or control the agent desktop from Cursor, add --share-desktop:

agent worker --computer-use --share-desktop start

--share-desktop takes an optional mode: view (watch only) or view_and_control (viewers can take mouse and keyboard control; the default). Sharing uses a worker-created, isolated agent desktop, not the machine’s own session, and requires tigervnc-standalone-server. A fail-closed input filter on the machine enforces control, and clipboard transfer stays blocked. Pixels leave the machine only through the worker’s existing outbound connection. No inbound ports open.

Verify with debug, then a real task

agent worker debug

On macOS, the report confirms Cursor Computer Use is installed. It does not check Accessibility or Screen Recording. Prove those by starting the worker and sending a task that asks the agent to open a browser, visit a page, and take a screenshot. The screenshot shows up in the chat when both permissions are in place. Debug does not prove macOS privacy grants.

On Linux, the report checks each required binary, whether the configured display is reachable, and whether the worker can fall back to a managed desktop.

If screenshots or clicks fail on a Mac worker, run agent worker debug first. If the install failed, check that the worker can reach downloads.cursor.com. If the helper is installed, grant Accessibility and Screen Recording to Cursor Computer Use, restart the worker, and run the task again.

Start a worker with --computer-use (add --share-desktop on Linux if you want viewers), then send a screenshot-and-click task and confirm the image lands in chat.

Sources

• Computer use and desktop sharing
• Self-hosted machines