Cursor Background Agents: Setup, Real Use Cases & What to Expect (2026)

You're in the middle of adding a new checkout flow when someone drops a Slack message: the auth module has a memory leak and it's hitting production. Fixing it means touching 12 files across three services. You can either drop everything now or let it fester until you've got a cleaner moment — which rarely comes.

Background agents are Cursor's answer to that kind of parallelism. Assign the fix to an agent, keep building your checkout flow, and review the PR when it's ready. Here's everything you need to actually use them.

What Background Agents Actually Do

Cursor's background agent — now officially called Cloud Agent in Cursor's docs — runs agentic tasks in an isolated cloud environment, not on your local machine.

When you assign a task, Cursor spins up a sandboxed Ubuntu VM, clones your repository, checks out a dedicated agent/<task-slug> branch from main, and works independently until the task is complete. When it's done, it opens a pull request and sends you a notification — via email, Cursor desktop, or Slack if you've connected it.

Three things make this distinct from the standard foreground agent:

Branch isolation: The agent never touches your working branch. It cuts a fresh branch from main, works there, and you decide whether to merge. You can keep coding on your own branch the entire time.

No babysitting: The foreground agent stops and asks you things. Background agents run to completion without interrupting you. That's a feature for well-scoped tasks and a liability for anything ambiguous.

No local machine required: Close your laptop. The VM keeps running. Your computer doesn't need to be on.

The feature launched in Cursor 0.50 in May 2025 as an early preview and rolled out to all Pro users in v1.0.

Setup Requirements

Before you can use background agents, four things need to be true:

1. Cursor Pro plan ($20/month) — background agents aren't available on Hobby
2. Usage-based spending enabled — go to cursor.com/dashboard and set at least a $10 spending limit
3. Privacy Mode disabled — the cloud VM needs to receive your code
4. GitHub or GitLab connected with read-write permissions to your repo

Cursor is SOC 2 Type II certified and states it doesn't retain code after a task ends. The code lives only in the isolated VM for the duration of the task.

Enabling Background Agent (Step by Step)

1. Open Cursor Settings → Beta → enable Background Agent
2. In the agent input dropdown, select Cloud instead of the default local mode
3. Go to Settings → Agent → Background → Repository Access and connect your GitHub repository
4. Set a spend limit at cursor.com/dashboard

After this, you can trigger background agents from:

• The Cursor IDE — switch mode to Cloud, type your task, send
• Slack — mention @cursor in any thread and describe what you need
• GitHub — comment @cursor on any issue or pull request
• Linear — mention @cursor in any issue
• Cursor Web — cursor.com/agents from any device, including mobile

The Slack integration is worth setting up. You're in a meeting, someone reports a bug, you type @cursor fix the misaligned button on the settings page and write a test for it — by the time the meeting wraps, there's a PR waiting.

Tasks That Work Well (With Actual Prompts)

The tasks that succeed in background mode share a pattern: clear scope, objectively measurable completion, no mid-task judgment calls.

Unit test generation

Add unit tests for all untested functions in src/services/payment/.
Match the naming conventions used in src/services/user/__tests__/.
Stop after covering 20 functions max.
Run npm test before opening the PR.

Dependency updates

Update all packages in package.json that have patch or minor version updates.
Run npm install and npm test after each individual package update.
If tests break after an update, revert that specific package and document it in the PR.
Don't update major versions.

Pattern-based refactoring

Replace all calls to fetchUser(id) with userService.getById(id) across the codebase.
The new interface is in src/services/user.ts.
See src/routes/profile.ts for a completed example.
Run the full test suite before creating the PR.

Accessibility fixes

Find all img tags in src/components/ with empty or missing alt attributes.
Add descriptive alt text based on each component's context.
Run the ESLint accessibility plugin check before the PR.

Documentation sweep

For every file in src/lib/ with no file-level JSDoc comment, add one.
Each comment: what the module does, what it exports, which modules import it.
Don't modify any implementation code.

A few prompt tips that make a real difference:

• Show one example — "Do this like the pattern in src/routes/profile.ts" cuts down wrong-direction work significantly
• Add a stop condition — "Stop after 20 functions" prevents the agent from over-completing and running up costs
• Tell it what to run — "Run npm test before the PR" means the PR arrives with a passing test suite
• Define graceful failure — "If a test fails after 3 fix attempts, leave a TODO and move on" gives the agent an exit instead of a loop

Tasks That Don't Work Well

Debugging an unknown failure. If you don't know why something is broken, the agent is guessing at every branch. Without you to redirect it, it can spend 30 tool calls going the wrong direction. Keep unknown-failure debugging in foreground mode.

UI or visual changes. "Make the card layout feel more modern" requires seeing the result. The agent produces something, but it can't evaluate whether it looks right — and neither can you until it's done. Stay in foreground for visual iteration.

Complex new features. A full OAuth integration spanning 15 files and multiple external APIs is not bounded enough. Background agents are good at execution, not discovery. Use foreground mode for anything where you'd ask "does this direction make sense?" mid-task.

Anything requiring mid-task decisions. Background agents run to completion without interrupting. If mid-task collaboration matters, use foreground mode.

Background Agent vs Claude Code vs OpenAI Codex

The practical call: use background agents for execution of tasks with clear success criteria. Use foreground Claude Code when you need to watch, redirect, and catch wrong turns as they happen. Codex CLI is strong if you're in a terminal-heavy workflow or want to trigger agent tasks programmatically.

Cost Management

Background agents always run in Max Mode, billed at API rates. A 20–30 step task with Claude Sonnet: roughly $0.30–$0.60. Tasks that spiral past 100 steps can reach $4–$5.

Ways to keep costs in check:

• Set a spend limit at cursor.com/dashboard before experimenting
• Check usage after the first few tasks to calibrate what your workload costs
• Add explicit stop conditions in prompts — agents that know when to stop don't run indefinitely
• Monitor running agents at cursor.com/agents and cancel anything clearly off track

What Background Agents Still Can't Do

Background agents are solid for code changes. The VM has a full terminal, can install packages, run tests, and browse the web via MCP — but the moment a task requires creating or publishing media, it hits a wall.

Here's where the gaps show up in real workflows:

Generating images or video. Say your agent finishes a landing page component and the PR description reads: "I couldn't generate the hero image — no image model available in this environment." The code is done; the asset isn't. This is common for marketing sites, documentation screenshots, or any task where visual output is part of the deliverable.

Publishing to a live URL. Background agents write files. They don't deploy. If a task ends with "please run npm run build and push to Vercel", that last step is left to you.

Live web research. By default, the cloud VM doesn't have web access. Tasks like "update our competitor pricing table" or "find the latest API docs for this SDK" need either MCP server integration or a separate search layer.

Audio generation. Music, voice narration, sound effects — not available in the VM.

Closing the Gap with AnyCap

AnyCap is a CLI designed specifically for agent workflows that need these capabilities. You install it once, and your agents — Cursor, Claude Code, Codex, or any tool with terminal access — can call it directly:

# Generate a hero image for the landing page the agent just built
anycap image generate \
  --model seedream-5 \
  --prompt "SaaS dashboard hero, dark background, data visualization" \
  -o hero.png

# Publish the finished site to a live URL
anycap page deploy ./dist --name "product-launch" --publish

# Search the web for current competitor pricing
anycap search --prompt "current pricing plans for Vercel, Netlify, Railway 2026"

# Generate background music for a video the agent produced
anycap music generate \
  --model suno-v5 \
  --prompt "upbeat product demo music, 90 BPM, no lyrics" \
  -o background.mp3

The practical pattern: use Cursor's background agent for the code work, and add AnyCap to the same task description when the deliverable includes media or a live URL:

Build the onboarding email template in src/emails/welcome.tsx.
Run npm test before the PR.

After the template is done, generate a preview hero image using AnyCap:
anycap image generate --model seedream-5 --prompt "welcome email header, warm colors, minimal" -o src/emails/assets/welcome-hero.png

The agent handles both steps in one pass — code change and asset — because it has terminal access to both Cursor's environment and AnyCap's CLI.

No separate dashboard, no API key wrangling per capability. One auth flow, one command pattern for image, video, music, search, crawl, and page hosting.

Add Capabilities to Your Workflow

If your agent tasks include media, publishing, or live web data alongside code changes, AnyCap works as a direct add-on — one install, callable from any terminal your agent already has access to:

npm install -g anycap
anycap login
anycap status  # confirm auth and available capabilities

From there, call image generation, page deploy, web search, or music generation using the same pattern shown above. No per-capability API keys, no separate dashboard.

→ anycap.ai

FAQ

Does the background agent need my local machine running?

No. The VM runs in Cursor's cloud. Close your laptop and it keeps working. You'll get an email and desktop notification when the PR is ready.

What does a task actually cost?

A typical 20–30 step task with Claude Sonnet: $0.30–$0.60. Complex tasks with 100+ steps: $4–$5. Set a spend limit and check usage after the first few runs.

Can I run multiple background agents at once?

Yes, and parallel execution is one of the main reasons to use them. Tests, documentation, and a bug fix can all run simultaneously on separate branches. Monitor them at cursor.com/agents.

Is my code safe with Privacy Mode off?

Cursor is SOC 2 Type II certified and doesn't retain code after a task ends. The code exists only in the isolated VM during the task. For teams with strict data requirements, consult Cursor's Enterprise documentation.

Background agent vs foreground — how do I decide?

If you can write the task as a clear instruction with measurable success, and it would take more than 10 minutes in foreground mode: use background. If you need to watch, redirect, evaluate visually, or debug an unknown failure: use foreground. Most developers end up using both — foreground for exploration, background for execution.