Cursor background agents: what they are and when to use them

First, the name changed

If you are searching for Cursor background agents you are searching for a feature that Cursor no longer calls that. It was renamed to Cloud Agents in Cursor 2.0, and the current documentation carries an explicit naming-history line saying so. The old documentation path redirects to cursor.com/docs/cloud-agent.

This matters for more than tidiness. Most of the writing about Cursor background agents describes the 2025 product, and the 2025 product had a different entry point, a different pricing model, and a different answer on Privacy Mode. If an article tells you to press Cmd+E or click a cloud icon in chat, it predates Cursor 3.0, which moved cloud agents out of the editor entirely and into the Agents Window.

What a Cursor background agent actually is

A Cloud Agent is an agent run that happens somewhere else. Cursor describes them as running in isolated VMs in the cloud with full development environments: your repository cloned, dependencies installed, secrets injected, startup commands run, and network access configured. The agent can then build, test, and interact with the software it is changing, which is the part that separates this from a chat that writes code it never executes.

The machine is Ubuntu. Cursor does not publish CPU, memory, or disk figures, and describes the default VM profile as having limited memory and CPU; custom resource configuration exists but is an Enterprise feature. Assume a modest box, not a build server.

That last row is the one that changes how you work. A Cloud Agent can only see what is committed and pushed. A half-finished refactor sitting in your working tree does not exist to it, and neither does the .env you never committed for good reasons. This is not a rough edge; it is the defining constraint of the model, and most of the friction people report traces back to it.

Every way to start one

The documentation lists seven surfaces, and there are two more worth knowing. The spread is the actual product insight here: Cursor is betting that the moment you want to delegate a task is often a moment you are not in your editor.

The Privacy Mode trap

There are two privacy settings with confusingly similar names and opposite outcomes. Cloud Agents are available in Privacy Mode: Cursor states that it never trains on your code and only retains code for running the agent. Cloud Agents are not available in Privacy Mode (Legacy), because legacy privacy mode blocks cloud data storage and a cloud agent has to store code and environment data while it runs.

If you turned privacy on years ago and never revisited it, you are probably on the legacy setting, and Cloud Agents will refuse to start with a message telling you to switch. That is the fix: switch to the current Privacy Mode. Any guide that flatly says privacy mode disables background agents is describing the legacy setting without naming it.

Setting up the environment

A fresh VM with your repository on it is not a working environment. Getting from one to the other is what .cursor/environment.json describes, and it is where most of the real configuration effort goes.

{
  "install": "pnpm install --frozen-lockfile",
  "start": "docker compose up -d postgres redis",
  "terminals": [
    { "name": "dev", "command": "pnpm dev" },
    { "name": "tests", "command": "pnpm test --watch" }
  ]
}

The unit that makes this fast is a Build, which Cursor defines as a bootable snapshot of a prepared Cloud Agent environment. Your install step is baked in once and the agent boots from the snapshot, rather than reinstalling your dependency tree every time you delegate a task. If a new Build fails, agents keep using the last successful one, which is the right failure mode.

Secrets, in three flavours

Because the machine is not yours, every credential your build or test suite needs has to be handed over deliberately. Cursor separates them by who can see them, which is a better design than a single flat list.

• Environment variables are visible to the agent. Use them for flags, public URLs, and configuration you would not mind reading in a transcript.
• Runtime secrets are redacted from the agent’s tool-call results, chat transcript, commits, and commit messages, replaced with [REDACTED]. Note the limit Cursor documents: they are still visible to a human interacting with the environment through the terminal.
• Build secrets are available only to the Docker build process and never reach the running agent. This is the right home for a private package registry token.

Network access has three settings: reach any external host, the default domains plus your allowlist, or your allowlist only. Allowlist-only is the interesting one for anyone with a compliance story to tell, and it is worth setting deliberately rather than discovering later, because an agent that can run arbitrary commands with unrestricted egress is a data-exfiltration surface if the prompt can be manipulated.

What it costs

The pricing question people ask is whether the VM is billed separately from the tokens. Per the documentation, no. Cursor states that Cloud Agents are charged at API pricing for the selected model, and that Builds are included with Cloud Agents at no additional cost.

• Model tokens are the meter. The context window size you pick affects token usage, and therefore cost.
• Included usage is spent first. Cloud agent tokens draw down your plan’s allowance before any on-demand charge begins.
• On-demand billing has to be enabled at all. Cloud Agents require it as a prerequisite, so an account with overage switched off cannot start one even with allowance remaining.
• The plan matters. Cloud Agents are listed on the paid tiers, not on Hobby.

Separately, be aware that Cursor removed dollar cost figures from its usage graph in August 2026, on the reasoning that plan usage in dollars is not what you are billed. That is defensible, and it also makes attributing spend to individual cloud agent runs harder than it was.

The limits worth knowing before you rely on them

This is the section most coverage skips, and it is the one that decides whether Cloud Agents fit your work.

How a run ends

The finish is genuinely good, and it is the part of the feature that most justifies it.

• It opens a pull request. The output arrives in the place your team already reviews code, rather than in a chat window you have to transcribe.
• It tries to fix CI it broke. Cloud Agents automatically attempt to fix CI failures they introduce, and skip that follow-up once a human pushes a commit to the branch. Turn it off globally in Cursor Dashboard, Cloud Agents, My Settings, or per pull request by commenting @cursor autofix off.
• Commits are signed. They carry the verified badge on GitHub and GitLab automatically, so agent authorship is legible in history rather than indistinguishable from yours.
• You can take the wheel. Cursor documents taking control of the agent’s remote desktop to interact with the software it is building, then handing control back to let it keep working. The terminals you configured run in a tmux session shared between you and the agent.

That last capability is underrated. The usual criticism of cloud agents is that you trade visibility for parallelism, and a shared terminal plus a remote desktop is a real answer to it, at least for the cases where you notice something has gone wrong in time.

When a local agent in a worktree is the better answer

Cloud Agents solve a specific problem: you want work done and you do not want it on your laptop or in your way. When that is the problem, they are the right tool. When it is not, moving the work to someone else’s VM adds setup, latency, and a class of failure you cannot debug.

The last row is the one worth dwelling on, because parallelism is the main thing people want from background agents and it is entirely achievable locally. A git worktree gives each agent its own checkout of the same repository, with its own branch and its own files, so several can work at once without overwriting each other. That is the same isolation property a cloud VM provides, on hardware you already own, with your environment already set up on it. The mechanics are in the complete git worktree guide, and the coordination problem is in multi-agent orchestration.

Cursor supports this directly: the CLI has a -w flag that creates the worktree for you. It is a genuine strength of the product and gets far less attention than the cloud story does.

None of that is an argument against Cloud Agents. The honest summary is that they are excellent at the thing they are for, delegating self-contained work to a machine that is not yours, and that a large share of real coding work is not self-contained. Most people who use both end up with a simple rule: if the task can be written down completely, send it to the cloud; if it needs your context, keep it local.

Questions people ask

Keep reading

Continue through Cursor with Cursor usage limits: Hobby, Pro, and on-demand, which meter actually stopped you.