Table of Contents
- What are Cursor background agents, and why are they now called Cloud Agents?
- How do Cursor background agents work under the hood?
- How do you set up and launch a Cursor background agent step by step?
- How much do Cursor background agents cost, and which models can you use?
- What tasks are Cursor background agents actually good at, and where do they fail?
- How do you review, modify, or take over a background agent's changes?
- Is your code safe in a Cursor cloud agent, and how are secrets handled?
- Why do background agent runs fail, and how do you fix them?
- Which alternatives to Cursor background agents should you consider?
- How did we compare these options?
- How do you get started with Agent 37?
- What do people also ask?
- What agents does Cursor have?
- Can I use my own agents in Cursor?
- What is the best Cursor agent to use?
- How do I turn off agent mode in Cursor?
- Are Cursor background agents free?
Do not index
Cursor background agents, now labeled Cloud Agents in the Cursor UI, are coding agents that clone your GitHub repository into an isolated cloud VM, work on a task while you keep coding, and hand back a branch or pull request. They need a paid Cursor plan and bill by usage on MAX-capable models. If you want the always-on part without Cursor's plan, model restrictions, or a VM that disappears after every task, we recommend Agent 37: a persistent Linux instance for Claude Code, Codex, Pi or Hermes from $3.99 per month. Agent 37 is not a Cursor plugin and does not run Cursor's Cloud Agents; it hosts open-source and CLI coding agents on a machine that keeps the repo, caches and sessions between runs.
Key takeaways
- Cursor renamed Background Agents to Cloud Agents in 2025; the docs and the API moved to the new name, but older tutorials, Reddit threads and the Cmd+E / Ctrl+E shortcut still say "background agent".
- Each Cursor Cloud Agent runs in a fresh, isolated VM that clones your repo through the Cursor GitHub app and is configured by a .cursor/environment.json file.
- Cloud Agents are not included on Cursor's free Hobby plan; they require Pro or higher and are billed by usage, with model choice limited to MAX-mode models.
- Agent 37 instances are persistent and always-on, from $3.99 per month.
- The best Cloud Agent tasks are small, well-specified and verifiable: bug fixes, test coverage, dependency bumps and mechanical refactors.
Key takeaways
- Cursor renamed Background Agents to Cloud Agents in 2025; the docs and the API moved to the new name, but older tutorials, Reddit threads and the Cmd+E / Ctrl+E shortcut still say "background agent".
- Each Cursor Cloud Agent runs in a fresh, isolated VM that clones your repo through the Cursor GitHub app and is configured by a .cursor/environment.json file.
- Cloud Agents are not included on Cursor's free Hobby plan; they require Pro or higher and are billed by usage, with model choice limited to MAX-mode models.
- Agent 37 instances are persistent and always-on, from $3.99 per month.
- The best Cloud Agent tasks are small, well-specified and verifiable: bug fixes, test coverage, dependency bumps and mechanical refactors.
What are Cursor background agents, and why are they now called Cloud Agents?
Cursor background agents are asynchronous coding agents that run on Cursor's cloud infrastructure. Cursor renamed them Cloud Agents in 2025 to describe where they run rather than how they behave. Both names refer to the same feature: an agent that clones your repo into a remote VM, completes a task on its own, and returns a pull request.
The rename is why searchers get confused. Cursor's changelog entries from the first half of 2025 say "background agent", the current docs say "cloud agent", and the editor still opens the same panel either way. If a tutorial you found talks about background agents, it is describing the feature you now see as Cloud Agents.
The practical difference is against the regular in-editor Agent. The in-editor Agent edits files on your machine while you watch, and it blocks you from doing much else in that workspace. A Cloud Agent works in a separate environment, so you can run several at once and keep using your editor.
A simple decision rule: use the in-editor Agent when you want to steer each step, and a Cloud Agent when you can describe the finished result in a paragraph and are happy to review a PR later.
How do Cursor background agents work under the hood?
When you launch a Cursor Cloud Agent, Cursor provisions an isolated virtual machine, clones your repository through the Cursor GitHub app, runs your install command, and lets the agent edit files, run terminals and execute tests. When it finishes, it pushes a branch and opens a pull request.
That isolation is the right default for untrusted code execution. The NIST Application Container Security Guide, SP 800-190, describes why per-workload isolation limits the blast radius when an automated process does something unexpected, and Cursor's model follows that pattern: one task, one VM, torn down afterward. You can read the guidance at NIST SP 800-190.
The trade-off is statelessness. Every run re-clones the repo, reinstalls dependencies unless a snapshot already contains them, and starts with no memory of yesterday's run. For a 20-minute bug fix that is fine. For long jobs, large monorepos, or an agent you want to talk to over days, a persistent machine is a better shape, which is the gap always-on AI agent hosting is built to fill: files and memory survive between tasks, and the instance stays on when you log off.
How do you set up and launch a Cursor background agent step by step?
To launch a Cursor Cloud Agent you connect GitHub through the Cursor GitHub app, open the Agent panel and choose the cloud option, configure the environment with a base snapshot or a .cursor/environment.json file, add any secrets in the dashboard, and submit a task prompt.
Here is the full path from zero to first PR.
- Install the Cursor GitHub app on the repository and grant read and write access. Most "agent never starts" reports trace back to this step.
- In Cursor, open the Agent panel and switch to cloud mode, or press Cmd+E on Mac and Ctrl+E on Windows and Linux. You can also start from the web dashboard at cursor.com/agents, which works on a phone browser.
- Set up the environment. Cursor can take an interactive snapshot of a machine you configure by hand, or you can commit a declarative file.
- Add secrets such as test database URLs in the agent settings UI, never in a committed file.
- Write a task the way you would brief a contractor: scope, acceptance criteria, and what not to touch.
A minimal .cursor/environment.json for a Node project looks like this:
{
"snapshot": "POPULATED_FROM_SETTINGS",
"install": "npm ci",
"start": "npm run build",
"terminals": [
{ "name": "tests", "command": "npm test -- --watch=false" }
]
}A task prompt that tends to succeed: "Add input validation to POST /api/orders so that quantity must be a positive integer. Return a 400 with a JSON error body. Add unit tests covering zero, negative and non-numeric input. Do not change the database schema." The resulting PR should contain a small handler change, a test file, and a passing run of the tests terminal.
Beyond the editor, you can trigger agents by mentioning @Cursor in Slack, assigning an issue in Linear, replying to a pull request on GitHub, or calling the Cloud Agents REST API, which is what people searching for "cursor background agent api" are looking for.
How much do Cursor background agents cost, and which models can you use?
Cursor Cloud Agents are not available on the free Hobby plan. You need Cursor Pro or a higher tier, and agent runs are billed on usage rather than a flat fee. Model choice is limited to MAX-mode models, so you cannot route a cloud task to the cheapest model in the picker to save money.
Cursor publishes Pro at $20 per month at the time of writing; confirm the current figure on cursor.com/pricing, because the plan structure has changed more than once. Usage above what your plan includes is charged on top, and Cloud Agent runs consume that usage quickly because every run re-reads the repo and iterates with tests.
The cost of a single task depends on repository size, how many files the agent reads, how many test cycles it runs, and which MAX model you pick. Cursor does not publish a per-task price, and neither will we invent one. A sensible rule is to run three representative tasks, open the usage dashboard, and divide spend by merged PRs before scaling up.
For comparison, Agent 37 separates compute from model spend. Hosting starts at $3.99 per month, and you pay the model provider directly with your own key or sign in with a Claude, ChatGPT or Copilot plan you already have. Full plan details are on the Agent 37 pricing page.
What tasks are Cursor background agents actually good at, and where do they fail?
Cursor Cloud Agents perform best on small, well-specified, verifiable work: fixing a bug with a reproducing test, adding tests to an existing module, bumping a dependency and resolving breakage, or applying a mechanical refactor across many files. They perform worst on large, ambiguous changes with no clear done condition, and on tasks that need services the VM cannot reach.
Concrete examples that users report working well include migrating a handful of components from one styling library to another, writing docstrings for a package, converting callbacks to async functions, and triaging a flaky test. Each has a boundary the agent can check itself.
Poor fits look like "redesign the onboarding flow" or "make the API faster". There is no test the agent can run to know it is finished, so it either stops early or wanders. Splitting that work into five bounded tickets usually produces better PRs than one open-ended run.
This matches the broader evidence on where AI coding assistance pays off. McKinsey's research on generative AI and developer productivity found the largest time savings on documentation and routine code tasks, with much smaller gains on complex, high-context work.
How do you review, modify, or take over a background agent's changes?
Every Cursor Cloud Agent finishes by pushing a branch and opening a pull request, so review happens in the normal GitHub flow or in the Cursor agent dashboard, where you can read the diff and the agent's log. You can send follow-up instructions to the same agent, or click Open in Cursor to check out the branch locally.
The follow-up loop is the underrated part. Instead of rejecting a PR and starting over, you reply with "the test you added mocks the wrong module, use the real client" and the agent picks up in the same environment.
What you do not get is a shell on the VM after the run ends, because the VM is gone. On a persistent instance that is different: Agent 37 exposes a full TTY terminal, a visual file browser and a live Linux desktop, all in the browser, so you can inspect exactly what an agent did and keep working on the same machine.
Is your code safe in a Cursor cloud agent, and how are secrets handled?
Cursor Cloud Agents run in isolated VMs that Cursor operates, so a copy of your repository leaves your machine and lives on Cursor's infrastructure for the duration of the task. Secrets added through the dashboard are stored encrypted. The main caveats are privacy mode behavior, which changed over time, and anything you bake into an environment snapshot.
Three checks before enabling the feature on a sensitive repo. First, read Cursor's current privacy page: early versions required Privacy Mode to be switched off, and the rules have since been revised. Second, confirm the retention period for code and snapshots in Cursor's policy rather than assuming it is zero. Third, make sure your GitHub app grant covers only the repositories you intend.
The .env trap deserves its own line. If you create a .env file while setting up an interactive snapshot, that file becomes part of the base image for every future run. Put credentials in the secrets UI instead, and keep .env in .gitignore.
Agent 37's model is different by design: your data stays in isolated containers, and API keys go directly to Anthropic, OpenAI or whichever provider you use. We never touch them, and the instance is yours to delete.
Why do background agent runs fail, and how do you fix them?
Most Cursor Cloud Agent failures fall into four buckets: the run never starts because the GitHub app lacks access to the repo, the agent cannot find a secret because it was placed in a file rather than the dashboard, the environment build fails on the install command, or tests fail because they need a service the VM cannot reach.
- Run does not start: reinstall the Cursor GitHub app on the specific repository, not just the organization, and confirm write permission.
- Missing secrets: add them in the Cloud Agent settings and reference them as environment variables; rebuild the snapshot if the agent still cannot see them.
- Environment build failure: run the install command yourself in the interactive setup and read the log; version pins and private registries are the usual culprits.
- Tests need Postgres or Redis: add a terminals entry that starts the service with Docker, or point the test config at a hosted instance via a secret.
If the same environment keeps breaking across runs, that is a sign the project wants a persistent machine rather than a rebuilt one. Set it up once, keep it on, and let the agent return to it.
Which alternatives to Cursor background agents should you consider?
If Cursor's plan requirement, MAX-only models or disposable VMs do not fit, the realistic alternatives are a persistent hosted machine such as Agent 37, OpenAI's Codex cloud tasks, the GitHub Copilot coding agent, Claude Code, and Devin. Each solves a different job, so choose by the task shape rather than by brand.
Published starting prices below are correct to the best of our knowledge at the time of writing; confirm on each vendor's pricing page before deciding.
Option | Best for | Pricing or format | Standout limit |
Agent 37 | Long-running or multi-day coding work on a machine that keeps repo, caches and sessions | From $3.99/mo; bring your own key or sign in with a Claude, ChatGPT or Copilot plan | Hosts Claude Code, Codex, Pi, Hermes and OpenClaw; does not run Cursor's own Cloud Agents |
OpenAI Codex cloud tasks | Parallel bounded tasks when your team already pays for ChatGPT | Included with ChatGPT paid plans, from $20/mo for Plus | Sandbox per task; OpenAI models only |
GitHub Copilot coding agent | Issue-to-PR automation inside GitHub without leaving the platform | Copilot Pro from $10/mo, consumes premium requests and Actions minutes | Scoped to GitHub repos and workflows |
Claude Code | Terminal-first agentic coding with deep repo reasoning | Included with Claude Pro from $20/mo, or pay per token via API | Runs where you launch it; keeping it always-on is your job |
Devin | Fully delegated tickets with a managed agent workspace | Core plan from $20/mo plus pay-as-you-go compute units | Compute units add up on long tasks |
For teams that want the Claude Code or Codex experience without the babysitting, we host both on persistent instances: see Claude Code hosting on a machine that keeps its state and Codex hosting that remembers where it left off.
How did we compare these options?
We compared each tool on three things: the published starting price or billing model on its pricing page, the plan required to use its cloud or background mode, and the scope of what it runs (which agents, which models, and whether the environment persists after a task).
How do you get started with Agent 37?
Add a card, nothing is charged, and you get a $5 starter credit, which makes your first instance free. Provision a Claude Code, Codex, Pi or Hermes machine with one API call, hand it a long job, and come back to a computer that still has the repo and the context.
What do people also ask?
What agents does Cursor have?
Cursor has the in-editor Agent that edits files on your machine, Cloud Agents (formerly Background Agents) that run in isolated cloud VMs and open pull requests, and integrations that launch Cloud Agents from Slack, Linear, GitHub comments, the web dashboard and a REST API.
Can I use my own agents in Cursor?
Not as a replacement for Cursor's Cloud Agents; those run Cursor's own harness on Cursor infrastructure. You can run your own agents such as Claude Code or Codex in Cursor's terminal, or host them on a persistent machine like Agent 37 and manage them from the browser-based terminal.
What is the best Cursor agent to use?
Use the in-editor Agent when you want to watch and steer each step. Use a Cloud Agent when the task is bounded, verifiable with tests, and you are happy to review a PR later. For multi-day work that needs a stateful machine, host Claude Code or Codex on a persistent instance instead.
How do I turn off agent mode in Cursor?
In the chat panel, switch the mode selector from Agent to Ask or Manual, or press the mode shortcut shown in the panel. To stop a running Cloud Agent, open the agent dashboard and cancel the run; it will not push further changes to the branch.
Are Cursor background agents free?
No. Cursor Cloud Agents are not on the free Hobby plan. They require Cursor Pro, published at $20 per month at the time of writing, or a higher tier, and runs are billed by usage on MAX-mode models. Confirm current plan details on cursor.com/pricing.