Skip to content
agents.cli

Flavour three - remote Cloud Agents

The third flavour 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.

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, with optional ports). 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:

  • Cursor Desktop - pick Cloud from the agent input.
  • Cursor web (cursor.com/agents) - drive it from any device, including your phone.
  • Slack - @cursor in a channel.
  • GitHub - comment @cursor on a PR or issue - the same handle as every other host.
  • Linear - @cursor on an issue.
  • REST API - spawn and manage agents programmatically, for webhooks and CI.

For budgetcli, 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. 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. Next: the three-flavour taxonomy.