Cursor Background Agents: Cloud vs Your Own Machine

"Cursor background agents" is still what people type, even though Cursor renamed the feature Cloud Agents. The forum threads that rank for it date from the 2025 early access, when it worked with GitHub only, billing was "not announced" and Privacy Mode had to be off. None of that is true anymore.

The short answer: a Cursor background agent is a coding agent that takes a task, works on it in an isolated VM in Cursor's cloud (or, since My Machines, on a machine of yours), and comes back with a branch and a pull request while you do something else.

This page covers what the feature is today, how to set one up, what it really costs (with the arithmetic), what happens to your code, and when a CLI agent on your own always-on machine is the better fit. Every Cursor fact below was checked against cursor.com/docs and the Cursor forum on 2026-10-27, with links.

Cursor background agents at a glance

Cursor Cloud Agents (formerly Background Agents)
What it is A Cursor agent that works on a task unattended, then pushes a branch and opens a pull request
Where it runs An isolated VM per agent in Cursor's cloud, with a full desktop; or your own machine with My Machines
How you start it Cursor editor (Cloud in the agent dropdown), cursor.com/agents, iOS app, Slack, GitHub, Bitbucket Cloud, Linear, the API, Automations
Repositories GitHub (Cloud and Enterprise Server), GitLab (Cloud and Self-Hosted), Bitbucket Cloud, Azure DevOps; multi-repo environments
What it costs Your plan's usage at the model's rate; no separate VM charge
Plans Premium ($30/month) and higher, Teams, Enterprise, legacy paid plans. Not Free, not Plus
Privacy Mode Supported (Legacy Privacy Mode is not)
Output Branch, pull request, screenshots, videos and logs attached to it
Parallel runs "As many agents as you want"

Sources: Cloud Agents docs, Cloud Agents help, Models & Pricing.

What happened to background agents: the Cloud Agents rename

Same feature, new name (and where the old name still shows)

The Cloud Agents reference ends with one line: "Cloud Agents were formerly called Background Agents." Cursor even keeps a help page titled What are background agents?, which defines them as "coding agents that typically run for a very long time" and adds "In Cursor, we call these Cloud Agents."

The old name survives in a few places: forum threads, tutorials and videos from 2025, and the API, where agent IDs still start with bc-. If a guide tells you to look for "Background Agent" in the editor, look for Cloud in the dropdown under the agent input instead.

What changed since the 2025 early access

The 2025 forum thread that still ranks first describes an early access program: GitHub only, billing to be announced. Since then, according to the current docs:

How Cursor Cloud Agents work

The VM, the environment and the snapshot of your repo

Each agent gets its own VM ("Firecracker-based microVM infrastructure", in a separate AWS account from the rest of Cursor's production, per the security page). It clones your repository, works on a separate branch and pushes it for handoff. You need read-write access to the repository and its submodules.

What the agent can do depends on its environment: the repositories, installed dependencies, secrets, startup commands and network access. Cursor's docs are blunt about it: "Not setting up a development environment for your cloud agents is like not giving your engineers a computer." An environment comes from an agent-led setup, a saved snapshot, or a Dockerfile referenced in .cursor/environment.json, and Builds prepare it in the background so agents start with dependencies already installed.

Starting one: editor, web (and phone), Slack, GitHub, Linear, API

curl --request POST \
  --url https://api.cursor.com/v1/agents \
  -u "$CURSOR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": { "text": "Fix the flaky test in auth.spec.ts" },
    "repos": [{ "url": "https://github.com/your-org/your-repo", "startingRef": "main" }],
    "autoCreatePR": true
  }'

The same API lists runs, streams a run's events, sends follow-ups, cancels, and manages environments and secrets. The legacy v0 API (/v0/agents) stays available during the migration.

Automations: schedules and event triggers

Automations (set up at cursor.com/automations) start Cloud Agents on a cron expression, or when something happens: a pull request opened or merged, a push, a CI run finishing, a Slack message, a Linear issue, a Sentry error, a PagerDuty incident, a webhook call. Two billing details matter: an automation "uses each model's maximum supported context window" with no toggle, and it bills either you or, on teams, a dedicated service account.

That is the kind of job a background agent suits best: a nightly issue triage, a weekly dependency update, a morning pull request review as an alternative to commenting @cursor on each pull request.

What comes back: branch, PR, screenshots and videos, authorship

The agent pushes its branch and opens a pull request (a draft, per the security page) with artifacts: "screenshots, videos, and logs so you can see exactly what changed and how the agent verified its work." You can also take control of the agent's remote desktop to try the change yourself.

Two details that catch teams out:

What does not follow you to the cloud

Setting one up step by step

Create the environment and connect the repo

  1. A Cursor admin connects source control for the account (GitHub, GitLab, Bitbucket Cloud or Azure DevOps).
  2. In the Cloud Agents dashboard, create an environment and select one or more repositories.
  3. Let the agent-led setup install dependencies, or commit a .cursor/environment.json:
{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "pnpm install",
  "start": "sudo service docker start"
}

install runs when a Build is created and "must be idempotent"; start runs each time an agent boots from that Build, followed by any terminals (processes in a tmux session you share with the agent). Paths in build are relative to the .cursor folder. Don't COPY the project into the image: Cursor checks out the right commit itself. See Cloud agent setup.

Each agent gets "a default VM profile with limited memory and CPU", with no published numbers. Enterprise teams can ask support for more; self-serve sizing is "coming soon". Cursor-hosted VMs are x86_64 only; for arm64, use My Machines or a pool.

Secrets and environment variables (and the "none of the secrets available" fix)

Add secrets in the dashboard; they reach the agent as environment variables, injected when it starts. Missing secrets are one of the oldest complaints on the forum, and the 2026 threads are still there. In order, check:

  1. Did the agent start before you added the secret? Agents already running don't pick up new secrets. Start a new one.
  2. Right team or account? "Secrets are workspace/team-scoped."
  3. Environment-scoped? On 2026-07-16, a Cursor staff member called it a known issue and wrote that defining the secrets "as personal/team scoped instead of environment scoped will serve as a reliable workaround" (thread).

For private package registries at build time, use Docker build secrets, not runtime secrets.

Docker and services in the start command

A Build keeps /var/lib/docker, so images and stopped containers carry over to new agents. The Docker daemon does not keep running, which is why sudo service docker start belongs in start. Long-running app processes (a dev server, a worker) go in terminals, so the agent and you can both see them.

Your first task, and good tasks to give it

Give it a task with a check the agent can run itself: a failing test to make pass, a bug with a reproduction, a dependency bump with a test suite, a UI change it can verify in the browser and film. Vague product work ("improve onboarding") comes back as a large diff you have to judge from scratch. Start with one small, well-specified task, read the pull request and its video, then widen.

How much do Cursor background agents cost?

Included usage first, then credit: what Cursor staff confirmed

The docs: "Cloud Agents use the same plan usage as Agent in the editor and the CLI, at the selected model's rate." The pricing thread on the forum shows why people are confused. On 2026-04-07, a Cursor staff member answered that Cloud Agents "are not included in standard usage plans". The same person corrected it on 2026-04-30: "Cloud agents actually do consume included API usage first before moving on to on-demand usage", with on-demand usage enabled. Pages written in April still quote the first answer.

On the current plans (Cursor is now sold as part of The X Subscription), what "included" means depends on the model:

No VM charge, but the model and context window drive the bill

On 2026-09-09, Cursor staff: "There's no separate VM, compute, or memory charge for Cloud Agents." Builds are included too. What moves the bill is tokens: which model, how much it reads, and the context window ("a larger context window can increase token usage and costs"; Automations always use the maximum). The spend-based rate limiter "requires at least ~$2 of headroom under your hard limit before a Cloud Agent run will start" (staff, 2026-04-30), and you set a spend limit the first time.

Legacy request-based plans and Max Mode

On the legacy request-based plans, Cloud Agents "always run in Max Mode, so they're priced at API rates plus the Max Mode upcharge and count against your included requests as request-equivalents rather than one request each." One long run can eat many requests.

Are Cursor background agents free?

No. Cursor's plan list on 2026-10-27:

Plan Price Cloud Agents
Free $0 No
Plus $8/month No
Premium $30/month Yes, "Cloud agents & automations"
Super $100/month Yes
Ultra $200/month Yes
Teams $30, $100 or $200 per seat/month Yes
Enterprise Custom Yes
Legacy Start, Pro, Pro+, Ultra Unchanged Yes

Sources: cursor.com/pricing and the Cloud Agents help page. Note the two Ultras: the legacy one and the $200 X Subscription tier. Staff also mention promotional allocations that make "the first few times you spin up a cloud agent environment" free.

A worked example: estimate one run from its token count

We have no Cursor transcript to show, but we do have real token counts from our Codex vs Claude Code benchmark: one Claude Code refactor run on claude-opus-5-5 (61.9 s) read 230,054 cached tokens, wrote 21,850 to the cache, sent 18 uncached and wrote 4,262 output tokens. Priced at Cursor's published rates on 2026-10-27:

Token type Tokens Claude Opus 5.5 rate Cost Composer 2.5 rate Cost
Input 18 $4/M $0.0001 $0.50/M $0.0109 (cache writes counted as input)
Cache write 21,850 $5/M $0.109 – –
Cache read 230,054 $0.20/M $0.046 $0.20/M $0.046
Output 4,262 $20/M $0.085 $2.50/M $0.011
Total 256,184 $0.24 $0.07

On a Teams seat, the Cursor Token Rate adds 256,184 × $0.25/M = $0.064 to the Opus run, so $0.30. On Composer, the run comes out of the weekly pool and costs nothing extra until the pool runs out.

Read this as a method, not a quote. Cursor's own agent has its own system prompt and tools, so the same task would not use exactly these tokens, and a real background task that installs dependencies, runs the suite and films the browser reads far more than a one-minute refactor. The bill scales with the tokens: a run that reads ten times more costs about ten times more. The usage page of your Cursor dashboard shows the real figure per request, and that is the number to watch for a week before you put agents on a schedule.

Is your code safe? Privacy Mode and where code goes

Privacy Mode is supported now (many guides still say otherwise)

Several articles in the top results say you must turn Privacy Mode off to use background agents. The current docs say the opposite: "Cloud Agents are available with Privacy Mode." With it on, "Cursor never trains on code accessed by Cloud Agents or on the prompts and responses their runs generate", and most models run under zero-data-retention agreements. The exception is Legacy Privacy Mode, which "is not supported for Cloud Agents, because agents need to store code and environment data in the cloud while they run." Some models also need extra approval with Privacy Mode: Cursor's pricing table flags Claude Fable 5 and 5.1 as requiring data retention approval.

What Cursor stores, per its security page:

Data Retention
Runtime workspace (the checkout) Recycled after the run goes idle
VM snapshots, including cloned code 30 days of inactivity, can't be deleted on demand
Conversation (prompts, responses, tool calls, diffs, artifacts) Kept indefinitely by default, deletable through the API
Secrets and tokens Until you remove them

What leaves your machine, by setup

No setup keeps code entirely on your machine while a hosted model reasons about it. The real question is how many companies see it and under which agreement.

My Machines: Cursor background agents on your own hardware

Setup in four commands

From My Machines, in the checkout of the repository the agent should work in:

curl https://cursor.com/install -fsS | bash      # Windows PowerShell: irm 'https://cursor.com/install?win32=true' | iex
agent login                                     # browser login, or --api-key with a personal key
agent worker start --name "my-devbox"           # keep it running
agent worker debug                              # if the machine doesn't show up

Then at cursor.com/agents, pick the machine under My Machines and send a task. From Slack or GitHub, add worker=my-devbox to the request (@Cursor worker=my-devbox fix the flaky test). Serve several repositories from one worker with repeated --worker-dir, let the agent drive the desktop with --computer-use (macOS and Linux), and, on Linux, open its files and terminal from the Cursor app with --connect-workspace.

What runs locally and what stays in Cursor's cloud

"The agent loop runs in Cursor's cloud, but terminal commands, file edits, browser actions, and other tool calls execute on your machine." Stdio MCP servers run on your machine and can reach your private network; HTTP MCP servers still run from Cursor's backend. The worker only opens outbound HTTPS (to api2.cursor.sh, api2direct.cursor.sh and a few download and artifact hosts): no inbound port, no VPN.

Two things don't change: inference and billing. "Every runtime option uses the selected model and follows its pricing", and with your own machines "you also pay for and operate" them. My Machines changes where your code executes, not who you pay for tokens.

Limits: the worker must stay up, one repo per API agent, pools need Enterprise

Cursor Cloud Agents vs a CLI agent on your own machine

Where the code runs, who runs the loop, who bills the tokens

Three setups get called "background agents". They differ on three questions most comparisons skip:

Cursor Cloud Agents Cursor My Machines CLI agent on your own always-on machine
Where code runs Cursor's VM Your machine Your machine
Who runs the agent loop Cursor Cursor The CLI itself (Claude Code, Codex, Copilot CLI, Antigravity CLI)
Who bills the tokens Cursor: weekly pool, then credit at the model's rate Cursor, same as Cloud Agents The subscription you already pay (Claude Pro/Max, ChatGPT, Copilot) or an API key
Machine to maintain None Yours, worker always on Yours, always on
Secrets Cursor dashboard The machine's own The machine's own
Computer use, video on the PR Built in macOS and Linux with --computer-use Not built in
Start from Editor, web, iOS, Slack, GitHub, Bitbucket, Linear, API, Automations Web, worker= in Slack, GitHub, Linear; API A terminal, or whatever drives the terminal remotely
Models Cursor's curated list Cursor's curated list Each CLI's vendor models

Cursor background agents vs Claude Code (cloud and local)

Claude Code now has the same two shapes. Its cloud sessions (claude.ai/code, the Claude app, claude --cloud "...") run on Anthropic's VMs on Pro, Max, Team and eligible Enterprise seats; they count "toward your plan's usage limits" and "there's no separate charge for the cloud VM". Like Cursor, they start from the remote branch, not your uncommitted work. Unlike Cursor, cloning and pull requests require GitHub (other hosts only as an uploaded bundle that can't push back). Team and Enterprise organizations can route them to self-hosted runners (public beta), the counterpart of Cursor's pools. And Claude Code in a terminal runs on any machine you keep on, steerable from a phone with Remote Control.

The deciding factor is usually billing. If you already pay for Claude Max, Claude Code's limits cover the work at a flat price; through Cursor, Claude models are billed per token from prepaid credit. If you live in Cursor and want Cursor's models, its pool covers the work and Claude Code adds nothing. Our Codex vs Claude Code benchmark has measured token counts and costs for both CLIs on the same tasks.

Codex cloud tasks and Copilot cloud agent, in one paragraph each

Codex cloud (docs) runs each task in its own workspace while your computer sleeps: you pick repositories, Codex sets up and tests the environment, and you commit or open a pull request when ready. You start tasks from ChatGPT on the web, mobile or desktop, from the CLI or from Slack, and local and cloud tasks share your ChatGPT plan's allowance (Codex pricing, checked for our benchmark on 2026-10-06).

GitHub Copilot cloud agent (formerly the coding agent, docs) works in an "ephemeral cloud development environment" on GitHub, starts from the agents panel, a chat or an issue, and opens one pull request per task. Its environment is set in copilot-setup-steps.yml, and a session has a 59-minute maximum that can't be extended.

When Cursor Cloud Agents are the better pick

When your own always-on machine is the better pick

The catch: an agent that runs unattended on your own machine runs with no one clicking "Yes", next to whatever that machine can reach. Read when --dangerously-skip-permissions is safe before you set one up: non-root user, disposable worktree, no personal credentials in reach, deny rules for pushes.

How we run background agents on our own machines (SideHub)

We build SideHub for that last branch. An agent daemon runs on our VPS (it also runs on a laptop or a Windows machine), one per repository, and starts the real CLI binaries (Claude Code, Codex, Copilot CLI, Antigravity CLI, Gemini CLI) in terminals there, signed in to the subscriptions we already pay. SideHub resells no model access and needs no API key; the agent loop is the CLI's own.

What that looks like day to day:

What SideHub does not do, that Cursor does:

Common problems and fixes

The agent cannot see my secrets

Start a new agent after adding a secret, check the team or account, and move environment-scoped secrets to personal or team scope (the staff workaround from July 2026). On My Machines, expect no dashboard secrets: give the machine its own credentials, scoped to the job.

The agent starts from old code (uncommitted changes)

Cloud Agents and "Move to Cloud" start from the remote repository, not your working copy. Commit and push the branch first, or stash. The same rule applies to claude --cloud.

"Usage limit" or blocked runs despite a paid seat

Check, in order: your plan includes Cloud Agents (Free and Plus don't); you have at least about $2 of headroom under your hard spend limit; you have prepaid credit if you picked a third-party model, since those never come out of the pool; on a legacy plan, on-demand usage is enabled. One forum user still reported being blocked after upgrading to a Premium Teams seat on 2026-09-15, with no staff answer yet: if all of the above is fine, that is a support ticket.

My machine does not show up in the picker

Run agent worker debug. Then confirm the worker process is still running, the Cursor app and the CLI use the same account, the worker directory has the expected Git remote, and outbound HTTPS to api2.cursor.sh and api2direct.cursor.sh is open. A worker= request also needs the machine's registered repository to match the target repository, or Cursor rejects it.

The verdict

Cursor background agents still exist, as Cloud Agents, and they are the easiest way to hand a task to an agent if you work in Cursor: no machine to run, Privacy Mode supported, videos on the pull request, no VM charge, tokens billed at the model's rate. My Machines is for when the work needs your machine's tools or network but you still want Cursor's agent and billing. If you already pay for Claude Code, Codex or Copilot and want that subscription, several CLIs and your own machine to do the background work, run the CLIs on an always-on box of yours, and keep a person between the agent's commits and the push.