Cursor background agents let you offload coding tasks to remote cloud VMs while you keep working locally. They clone your repo, work on a branch, and open a PR when done. Think of them as async AI teammates that run in parallel.
Since launching with Cursor 1.0 in mid-2025, background agents have evolved rapidly. The February 2026 "Cloud Agents with Computer Use" update gave each agent its own VM with browser access and video recording. 35% of Cursor's own internal merged PRs are now created by these agents.
This guide covers how background agents work, what they cost, where they shine, and how they compare to alternatives like Claude Code and OpenAI Codex.
What Are Cursor Background Agents?
Background agents are asynchronous remote agents that run in isolated Ubuntu cloud VMs. Unlike Cursor's standard Agent mode (which runs inline in your editor, one task at a time, on your local files), background agents operate independently in the cloud.
| Feature | Agent Mode | Background Agents |
|---|---|---|
| Execution | Local, in your editor | Remote, in a cloud VM |
| Parallelism | One task at a time | Multiple agents simultaneously |
| Workflow | Interactive, real-time | Async, fire-and-forget |
| Output | Direct file edits | Pull request on a branch |
| Environment | Your local machine | Isolated Ubuntu VM |
| Privacy Mode | Supported | Must be disabled |
How Cursor Background Agents Work
Background agents need three things before you can use them:
1. Disable Privacy Mode
Your code must be sent to remote environments. Privacy Mode blocks this. Organizations that enforce Privacy Mode cannot use background agents.
2. Fund Usage-Based Spending
Background agents bill separately from subscription credits. You need at least $10-$20 in usage-based funding to get started.
3. Connect GitHub
Agents clone your repo and push branches. Grant read-write access to your repositories (and any submodules or dependencies).
The Workflow
Press Ctrl+E to open background agent mode. Write your prompt describing the task. The agent clones your repo into a fresh Ubuntu VM, works on a separate branch, and pushes a PR when done. You get a notification and can review the changes.
Each VM is isolated. Agents have internet access, can install packages with apt or npm, run builds, execute tests, and access external services. If your project has specific system requirements, you can define a Dockerfile to customize the environment.
Example: Custom Dockerfile for background agents
# .cursor/Dockerfile
FROM ubuntu:22.04
# Install project-specific system dependencies
RUN apt-get update && apt-get install -y \
nodejs npm postgresql-client redis-tools
# Install specific compiler versions
RUN npm install -g bun@1.0.26
# Set up environment
WORKDIR /workspaceCloud Agents with Computer Use
On February 24, 2026, Cursor shipped a major upgrade: Cloud Agents with Computer Use. Each agent now gets its own full development environment with a desktop, browser, and the ability to interact with UI elements.
Visual Testing
Agents open browsers, navigate to localhost, click through UI elements, and verify that their code changes actually work visually.
Video Proof
Agents record video demos of their work. Instead of mentally simulating a diff, reviewers watch a 30-second video of the feature in action.
Screenshot Artifacts
PRs include screenshots and logs alongside code changes. Reviewers get visual evidence, not just diffs.
Remote Desktop Access
You can connect to the agent's remote desktop, use the modified software yourself, and make manual edits without checking out the branch locally.
Multi-platform availability
Cloud agents are accessible from Cursor desktop, web, mobile, Slack, and GitHub. You can trigger an agent from your phone and review the PR from your laptop.
Pricing and Costs
Background agents require a paid Cursor plan. But the subscription price is just the starting point. The real cost is usage-based credits.
| Plan | Monthly Price | Credit Pool | Background Agents |
|---|---|---|---|
| Hobby (Free) | $0 | None | Not available |
| Pro | $20/mo | $20 credits | Available (overages likely) |
| Pro+ | $60/mo | 3x credits ($60) | Available |
| Ultra | $200/mo | 20x credits (~$4,000 value) | Best value for heavy use |
| Teams | $40/user/mo | Per-user credits | Available |
The real cost of background agents
Background agents always use MAX mode, which adds a 20% surcharge on credit costs. One agent run on a 50,000-line codebase can consume 22.5% of a Pro plan's monthly credits. Daily agent users typically spend $60-$100/month total. Power users running multiple agents often exceed $200/month.
If you plan to use background agents regularly, the Ultra plan at $200/month offers the best economics. Pro plan users will hit overages on even moderate agent usage.
When Background Agents Shine (and When They Don't)
Background agents work best for well-scoped, isolated tasks that you could describe in a clear GitHub issue.
Good Fits
Bug Fixes
Clear reproduction steps, isolated scope. The agent can clone, reproduce, fix, and verify the fix with tests.
Pattern-Following Features
New API endpoint that follows existing conventions. New UI component matching an established design system.
Test Coverage
Writing tests for untested modules. The agent reads existing tests for patterns, then generates matching tests for uncovered code.
Migrations and Scripts
Database migrations, data transformation scripts, dependency upgrades. Mechanical work with clear inputs and outputs.
Poor Fits
Ambiguous Requirements
Tasks that need back-and-forth clarification. The agent cannot ask follow-up questions mid-run.
Cross-System Changes
Deeply interconnected modifications across many services. The agent works in isolation and lacks broader system context.
Cursor Background Agents vs Claude Code
The architectural difference is fundamental. Claude Code runs on your local machine with direct filesystem access, full terminal visibility, and interactive conversation. Background agents run in remote cloud VMs asynchronously, producing PRs you review later.
| Dimension | Cursor Background Agents | Claude Code |
|---|---|---|
| Execution | Remote cloud VM | Local machine |
| Workflow | Async, PR-based | Interactive, conversational |
| Context Window | 70K-120K usable (reported) | Full 200K tokens |
| Parallelism | Multiple agents at once | One session (or Agent Teams) |
| Local Context | None (clean-room clone) | Full (sees your terminal, git state, processes) |
| Output Format | GitHub PR with video/screenshots | Direct file edits + conversation |
| Privacy | Code sent to cloud (required) | Local execution, optional cloud |
| Cost Model | Credit-based with MAX surcharge | API usage or subscription |
| Visual Testing | Built-in browser + video | Via MCP (Playwright, etc.) |
Claude Code excels at interactive development where you need back-and-forth conversation, full context awareness, and local integration. Background agents excel at parallel async execution where you want multiple tasks running without blocking your workflow.
Many developers use both
Claude Code for deep, interactive work on core logic. Background agents for parallel task execution on well-scoped tickets. The tools complement each other rather than competing directly.
Cursor Background Agents vs OpenAI Codex
OpenAI Codex takes a similar cloud-sandbox approach. Both tools spin up isolated environments, work asynchronously, and produce PRs. The differences are in execution details.
| Dimension | Cursor Background Agents | OpenAI Codex |
|---|---|---|
| Internet Access | Enabled during execution | Disabled during execution |
| Model Choice | Multiple models available | Purpose-built codex-1 only |
| IDE Integration | Deep (built into Cursor) | Standalone / ChatGPT interface |
| Browser Testing | Full computer use + video | Code-only execution |
| Environment Setup | Dockerfile customization | AGENTS.md + setup script |
| Access | Any paid Cursor plan | ChatGPT Pro/Plus/Team/Enterprise |
Cursor's internet access during execution is a notable advantage. Agents can install packages, fetch resources, and hit external APIs. Codex disables internet during task execution for security, limiting the agent to whatever is in the repo.
Limitations and Known Issues
Background agents are powerful but not without tradeoffs. Community feedback from the Cursor forum and Reddit surfaces several recurring issues.
Premature Completion
Agents sometimes claim a task is done when it is not. The code compiles but does not actually implement the requested behavior. Always review PRs carefully.
Cost Surprises
The MAX mode 20% surcharge plus credit consumption means costs add up faster than expected. A simple PR can cost $4-5 in credits.
Privacy Requirements
Privacy Mode must be disabled. For security-conscious organizations or regulated industries, sending all code to remote VMs may be a dealbreaker.
No Programmatic API
There is no official API to trigger background agents from CI, Jira, or other systems. You must use the Cursor UI. This limits automation workflows.
Security surface area
Background agents have a larger attack surface than local agent mode. Prompt injection from malicious web content encountered during browsing could potentially exfiltrate code or secrets. Cursor has implemented sandboxing and security controls, but the risk profile is inherently higher than local-only execution.
Stability
The Cursor forum has threads about stability issues: agents hanging, failing to complete, or producing inconsistent results across different model choices. These issues have improved with recent updates, but the feature is still maturing.
Tips for Getting the Most Out of Background Agents
Write Detailed Prompts
Include context, acceptance criteria, and references to existing patterns. The agent cannot ask clarifying questions, so front-load all the information it needs.
Scope Tightly
One clear task per agent. 'Add a /users endpoint following the pattern in /posts' beats 'refactor the API layer.' Smaller scope = higher success rate.
Include Test Instructions
Tell the agent how to verify its work. 'Run bun test after changes' or 'Navigate to localhost:3000/settings and verify the toggle works.'
Use a Dockerfile
Match your local environment. System dependencies, package manager versions, database clients. A mismatched environment produces broken builds.
Example: Well-structured background agent prompt
Task: Add rate limiting to the /api/search endpoint.
Context:
- Existing rate limiting middleware is in src/middleware/rate-limit.ts
- Follow the same pattern used by /api/chat (see src/app/api/chat/route.ts)
- Use Redis for rate limit storage (connection config in src/lib/redis.ts)
Requirements:
- 100 requests per minute per API key
- Return 429 with retry-after header when exceeded
- Add tests matching the pattern in tests/api/chat.test.ts
Verification:
- Run "bun test" to confirm all tests pass
- Run "bun run typecheck" to confirm no type errorsReview Every PR
Do not merge agent PRs without review. Even with video demos, check edge cases, error handling, and security implications. The agent optimizes for the happy path. Your job is to catch what it missed.
Decision Framework: Background vs Interactive
Use this to decide when to reach for background agents versus interactive tools like Cursor Agent mode or Claude Code.
| Scenario | Best Tool | Why |
|---|---|---|
| Well-scoped bug fix | Background Agent | Clear input, isolated scope, no back-and-forth needed |
| Exploring unfamiliar code | Interactive (Agent mode / Claude Code) | You need to ask questions and iterate |
| 5 independent tickets | Background Agents (parallel) | Run all 5 simultaneously, review PRs when ready |
| Core architecture refactor | Interactive (Claude Code) | Needs deep context, conversation, and careful human judgment |
| Adding tests to stable module | Background Agent | Mechanical, pattern-following, well-scoped |
| Debugging production issue | Interactive (local) | Needs access to logs, processes, and real-time system state |
| UI component from design spec | Background Agent (with Computer Use) | Agent can build and visually verify against the spec |
The pattern is straightforward: use background agents for parallelizable, well-defined tasks. Use interactive tools for exploratory, context-heavy, or judgment-intensive work.
FAQ
Do background agents work with private repos?
Yes, but you must grant Cursor read-write access to each private repository through the GitHub integration. The agent clones via GitHub, so any repo it can access works.
Can I use background agents with GitLab or Bitbucket?
As of March 2026, background agents require GitHub. GitLab and Bitbucket are not officially supported for the clone-and-push workflow.
How long do background agent sessions last?
Sessions can run for extended periods. Cursor 2.5 introduced "long-running agents" that plan first and work autonomously over longer horizons. There is no hard timeout, but costs accumulate with session length.
Can background agents access my local environment or databases?
No. Agents run in isolated cloud VMs with no access to your local machine, local databases, or local services. If your task requires a specific database state, you need to provide setup scripts or use a Dockerfile to configure the environment.
Do background agents support monorepos?
Yes. The agent clones the entire repository. For monorepos with submodules, ensure you grant GitHub access to all dependent repos so the agent can fully initialize the workspace.
What models do background agents use?
Background agents use whatever model you have selected in MAX mode. This includes Claude 3.5/3.7 Sonnet, GPT-5.4, and other available models. The model choice affects both quality and credit consumption.
Can I cancel a running background agent?
Yes. You can stop a background agent from the Cursor UI at any time. Any work already pushed to the branch will remain available, but incomplete tasks may leave the branch in a partial state.
Build Faster with Morph
Morph provides the fast apply model that powers code editing in tools like Cursor. Apply code changes 3x faster with our optimized models.