Cursor Cloud Agent vs Local Agent: When to Use Which
Cursor Cloud Agents and the local Agent (editor sidepane chat) share the same fundamentals—instructions, tools, model—but they run in different places. Cloud runs in an isolated VM; local runs in your open workspace. No pricing or personal reviews.
This is not a button tour. It covers only when Cloud fits PR/long jobs, when local chat is better, and how to hand off. Grounded in Cursor Cloud Agents and the Agent overview.
What is Cloud Agent good at?
One-line answer: Work that should not pin your laptop—long-running, parallel, branch/PR delivery. Isolated VMs can build, test, and drive desktop/browser when the environment is set up.
Official strengths:
| Axis | Why Cloud |
|---|---|
| Runtime | Isolated Ubuntu VM; not tied to your laptop power/network |
| Parallelism | Run many Cloud Agents at once |
| Delivery | Separate branch → push / PR handoff |
| Verification | Build, test, artifacts (screenshots, logs) when env is ready |
| Entry points | Desktop (Cloud), cursor.com/agents, Slack / GitHub / Linear @cursor, API |
Signals to pick Cloud:
- Goal is issue → reviewable PR/branch.
- Likely tens of minutes+; you do not want a local chat glued open.
- Dependencies, secrets, and network already live in the Cloud env (
.cursor/environment.json, Secrets, MCP). - You want to kick off from Slack / issue tracker with a mention.
- Change spans multiple repos (docs note multi-repo support; long-running may still be limited there).
Without an environment, Cloud is closer to “a remote notepad that writes code.” Docs stress environment setup as the main lever—fix install, Dockerfile, and Secrets before dumping long jobs.
When is local better?
One-line answer: Prefer the local Agent when you need the open files, local terminal, and checkpoints and will steer in short turns.
Local strengths:
| Axis | Why local |
|---|---|
| Context | Unsaved buffers, local-only files, debugger/device on this machine |
| Feedback | Immediate follow-ups (queue / steer) |
| Rollback | Session Checkpoints for Agent edits (separate from Git) |
| Secrets/policy | User hooks under ~/.cursor, keychain, board/USB not on the VM |
| Exploration | Fast “where is this used?” → small patch |
Signals to pick local:
- Scope still fuzzy—ask/plan first, then small patches.
- Hardware, emulator, or VPN-only tools exist only on the laptop.
- Uncommitted experiments you want to roll back via checkpoints.
- Cloud cannot reproduce yet—pin the repro command locally first.
- Policy forbids putting certain secrets/data on a remote VM.
Local Agent also has terminal, browser, and edit tools. The split is less “capability” than whose machine and session hold the work. Close the laptop and long local loops die; Cloud is the opposite.
How do you hand off?
One-line answer: Cloud hands off via branch/PR, artifacts, and agent URL; local hands off via diff, repro command, and a short brief into Cloud (or human review). Do not trap context on one side.
Local → Cloud
- Bundle repro command, failing log, scope paths, non-goals.
- Paste into the issue/Linear body or the Cloud kickoff prompt.
- Confirm the Cloud env can run the same repro (Secrets, install).
- Start from Desktop Cloud, cursor.com/agents, or
@cursor. - Review PR/branch/artifacts; optionally verify via remote desktop without a local checkout (per docs).
Prompt skeleton:
Goal: open a PR that <outcome>.
Repro (must exit 0 when done):
<command>
Scope: <paths>
Out of scope: <list>
Notes from local session:
<1–5 bullets: hypothesis, files already tried>Cloud → local
- Pull the PR/branch (or review the diff in UI).
- Pass CI, artifacts, agent conversation URL into local chat.
- Leave only leftovers (naming, edge cases, local-only checks) to the local Agent.
- If secrets live only in Cloud Secrets, ensure local has what it needs before re-running (docs: running agents do not pick up newly added secrets—start a new run).
One-page split
| Stage | Owner |
|---|---|
| Clarify fuzzy asks; file exploration | Local |
| Long edit + test + PR draft | Cloud |
| Board/USB / unsaved-buffer checks | Local |
| Team share / review link | Cloud agent URL / PR |
Formerly named Background Agents; today Cloud Agents. Treat old UI labels as the same family.
Wrap-up
Cloud Agent fits isolated VMs, parallelism, branch/PR, and remote verification. Local Agent fits the open workspace, instant steering, checkpoints, and local-only resources. The decision axis is long job/PR vs short interactive edit, not a feature checklist. Handoff = explicit repro, scope, and PR/artifacts both ways.