Command reference · Cursor CLI
agent worker
Parent command for starting a private cloud worker that runs agent tasks in your own environment.
agent worker connects your own machine to Cursor and lets cloud-agent tasks run there instead of in Cursor's own cloud environment (self-hosted). Contains the start and debug subcommands. The worker is configured via flags like --worker-dir, --name, --label or --labels-file, --pool or --pool-name, and --idle-release-timeout.
✅ WHEN TO USE IT?
Provide your own hardware/environment for cloud-agent runs (privacy, special tooling)
agent worker start --name build-worker-1 --worker-dir ~/repos/myapp
Register several workers as a pool that cloud agents can draw from
agent worker start --pool --pool-name ci-pool
⛔ WHEN NOT TO?
Only a single local agent run is needed
agent worker starts a long-running process connected to Cursor for cloud-agent handoffs, not a one-off run.
Better: Use a normal interactive session with agent or agent -p
Configuration/connectivity should be checked before actually starting
agent worker start connects immediately; auth, privacy, or routing problems only surface afterwards.
Better: Run agent worker debug first to see preflight diagnostics
SOURCES
- Cursor Docs — CLI Reference: Parameters ↗ cursor.com