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:
- More Git hosts: GitLab (including self-hosted), Bitbucket Cloud and Azure DevOps, plus multi-repo environments where one agent changes several repositories and opens a pull request in each.
- More places to start one: Slack, Linear, GitHub and Bitbucket comments, an iOS app, a public API.
- Automations: agents on a cron schedule or on events from GitHub, GitLab, Slack, Linear, Sentry, PagerDuty and webhooks.
- Computer use: the VM has a desktop; the agent drives a browser with mouse and keyboard and attaches screenshots and videos to the pull request (announcement).
- Self-Hosted Machines: My Machines for one developer's laptop or devbox, Team Pools for Enterprise fleets.
- A published billing model, covered below.
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
- Cursor desktop: select Cloud in the dropdown under the agent input.
- Web and phone: cursor.com/agents, the Cursor iOS app, or on Android the same page installed as a Progressive Web App.
- Slack and Linear: mention
@Cursor. - GitHub: comment
@cursoron a pull request or issue. Bitbucket Cloud: on a pull request. - API: the Cloud Agents API v1 (public beta):
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:
- Authorship. "Cloud Agent commits are authored as the agent, not as the person who started it." Commits are signed and show as Verified on GitHub. If a review rule requires a second reviewer on agent work, match the agent's author identity: the
Co-authored-bytrailer "isn't added for every agent." - Autofix. On Teams plans, Cloud Agents try to fix GitHub Actions failures on the pull requests they created. Comment
@cursor autofix offto stop it on one pull request.
What does not follow you to the cloud
- Uncommitted changes. "Move to Cloud" "does not snapshot your local uncommitted changes. The cloud agent starts from a clean git state on the remote repository." Commit and push, or stash, first.
- User-level hooks. Only command-based hooks from the repository's
.cursor/hooks.jsonrun (plus team and enterprise hooks on Enterprise). Not~/.cursor/hooks.json, not prompt-based hooks, not hooks packaged in plugins, and on Cursor's VMssessionEndnever fires. - Personal skills, unless you turn on Sync Skills for Cloud Agents under Settings → Agents. Project skills in the repository are always available.
- Your local MCP setup. MCP servers are configured for the team, from the MCP dropdown at cursor.com/agents (HTTP and stdio, OAuth supported).
Setting one up step by step
Create the environment and connect the repo
- A Cursor admin connects source control for the account (GitHub, GitLab, Bitbucket Cloud or Azure DevOps).
- In the Cloud Agents dashboard, create an environment and select one or more repositories.
- 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:
- Did the agent start before you added the secret? Agents already running don't pick up new secrets. Start a new one.
- Right team or account? "Secrets are workspace/team-scoped."
- 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:
- Cursor models (Grok 4.7, 4.6, 4.5, Composer 2.5) draw on your plan's usage pool, which refreshes weekly. Beyond it, top-ups pay the listed rates.
- Third-party models (Claude, GPT, Gemini) are never in the pool: on Premium and above they are billed "at the model's API list price from the first request, paid from your prepaid credit."
- Teams and Enterprise add a Cursor Token Rate of $0.25 per million tokens on eligible third-party models, on input, output and cached tokens. Individual plans don't pay it.
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
- Cursor-hosted Cloud Agents: the whole repository is cloned into Cursor's VM, and the conversation lives on Cursor's backend.
- My Machines: "The full checkout, build cache, and machine-local credentials stay on your machine." But the worker sends "the content the agent needs, such as file contents, terminal output, diffs, screenshots, local MCP results, and routing metadata", because the agent loop runs at Cursor.
- A CLI agent on your own machine (Claude Code, Codex): the checkout stays home, and the files and tool results the CLI reads go to its model provider, the same way they do when you use it at your desk.
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 upThen 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
- The worker must stay running. If no machine matches, a
worker=request "fails instead of falling back to another environment." - Dashboard secrets don't reach it. "The machine keeps its own tools, credentials, and network, and gets no dashboard secrets."
- One repository per agent started on a machine through the API; several repositories need an any-repo pool.
- You own the state: wiping it between runs, refreshing the checkout, repairing dependencies.
- Team Pools (
agent worker --pool start, Kubernetes, autoscaling, GPU workers) require Enterprise and a service account key. Personal workers need a personal credential.
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
- You work in Cursor and want the agent's results in the same place.
- You want no machine to maintain: Cursor provisions, isolates, snapshots and recycles VMs.
- You want proof on the pull request: screenshots and videos of the agent clicking through the change.
- You trigger work from Slack, Linear, Sentry or PagerDuty, or want many agents in parallel without capacity planning.
- Your repositories live on GitLab, Bitbucket or Azure DevOps (Claude Code's cloud sessions need GitHub).
When your own always-on machine is the better pick
- You already pay for a CLI subscription and want a flat cost: Claude Max, ChatGPT or Copilot limits instead of per-token credit.
- The task needs what only your machine has: a local database with real data, a GPU, a private network, a Windows box, a licensed tool.
- You want several CLIs, not only Cursor's agent: Claude Code for one step, Codex for another, Antigravity CLI or Gemini CLI for a third.
- You want commits under your own Git identity, with your machine's credentials and hooks.
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:
- Several CLIs, one cockpit. Every terminal and its CLI's state (working, waiting for input, idle) shows in one place, and we start, follow and answer them from a phone, including Claude Code's permission and multiple-choice questions.
- Work while no app is open. Scheduled prompts run on cron expressions; workflows chain steps, each with its own CLI. This very article came out of one: a weekly workflow picks a keyword and writes a brief, Claude Code drafts on the VPS, and a person reviews it before it goes live.
- A second CLI reviews before anything ships. The Claude codes, Codex reviews template has Claude Code implement unattended, Codex review the diff read-only, and a person validate. A run that changed the repository lands in To review with its diff, and SideHub only pushes the reviewed HEAD after someone confirms it under To push, never by itself.
- The cost of each run, measured. The agent reads the tokens of each run from the CLI's own transcript, so a scheduled job's cost is a number, not a guess. When a CLI stops on its plan's usage limit, the run is marked that way, with the reset time when the CLI gives one.
What SideHub does not do, that Cursor does:
- No managed VM. You bring the machine and keep it running.
- No computer use and no video of the change on the pull request.
- No Slack or Linear trigger. Workflows start from a schedule, a webhook, the API, an event in the workspace, or a click.
- No IDE. It is a cockpit for terminals, not an editor.
- No automatic fallback to another CLI when one hits its plan limit, yet.
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.