Flavor three - remote Cloud Agents

The last of the chapter’s three flavors leaves your machine entirely. Cloud Agents (formerly Background Agents) are full agents that run in isolated cloud VMs rather than locally: they clone your repo to a fresh branch, work, push results back, and you review the branch like any other. One gate to know up front - they require a paid Cursor plan (the docs’ troubleshooting: “You need to be on a paid Cursor plan”), so on the free tier this course assumes you can follow this page’s ideas but not start one (the pricing docs list Cloud Agents from the Premium tier up, as of October 2026). Those VMs are Cursor-hosted by default; the Cloud Agents API can also route runs to worker pools you host yourself, when execution needs to happen on hardware you control (API endpoints). Everything on this page is as of September 2026 (Cloud Agents documentation).

The environment they run in is reproducible from a checked-in file, .cursor/environment.json, configured one of three ways:

• Agent-led setup - the agent installs what it needs interactively, and you snapshot the result.
• A saved snapshot - a captured machine image the agent boots from.
• A Dockerfile - a fully declared, reproducible build environment.

The snapshot path looks like this - illustrative, not the full schema:

{
  "snapshot": "POPULATED_FROM_SETTINGS",
  "install": "npm install",
  "start": "npm run dev",
  "terminals": [
    { "name": "tests", "command": "npm test -- --watch" }
  ]
}

The snapshot, install, start, and terminals fields are the real field names (terminal entries take a name and command (an optional description is also defined); ports is a separate top-level array). One thing the example deliberately leaves out: the Dockerfile mode doesn’t use a bare snapshot field - it uses a build object ({dockerfile, context}) instead. The canonical schema is published at cursor.com/schemas/environment.schema.json; consult it before treating any one example as the whole story.

Because a Cloud Agent doesn’t live in your editor, it’s reachable from wherever your work already happens. Before anyone can start one from a repository, a Cursor account admin has to connect source control for the account - GitHub, GitLab, Bitbucket, or Azure DevOps. After that:

• Cursor Desktop - pick Cloud from the dropdown under the chat box where you prompt the agent.
• Cursor web (cursor.com/agents) - drive it from any device.
• Cursor for iOS - start and manage agents from the iOS app (on Android, cursor.com/agents installs as an app).
• Slack - @cursor in a channel.
• GitHub - comment @cursor on a PR or issue.
• Bitbucket - comment @cursor on a PR.
• Linear - @cursor on an issue.
• Microsoft Teams - @Cursor with a prompt, via the Teams integration.
• The API - spawn and manage agents programmatically, for webhooks and CI.

For budgetcli - the course’s illustrative personal-finance API - a Cloud Agent is the right tool when the work shouldn’t tie up your local machine and doesn’t need your eyes mid-flight: “open a PR upgrading the test dependencies and confirm the suite still passes” is a job you fire from Slack on the way out and review as a PR when it’s green. Your laptop never enters the loop, but cloud access, repository credentials, network access, secrets, and trigger authorization still need their own controls.

That puts all three machines on the table - this chapter’s fleet fan-out, delegated subagents, and these remote Cloud Agents. What is left is the part that actually saves you time in a working week: telling them apart fast enough to reach for the right one before you have spent the compute on the wrong one - a cost-and-control call in the course’s terms: what each flavor spends, and what boundary its machine puts around the run. Next: the three-flavor taxonomy.