Cursor Background Agent: Cloud Runs and How to Start One

Key takeaways

• A Cursor background agent runs asynchronously in an isolated cloud VM, clones your repo, works on its own branch, and hands off the result as a pull request.
• You can trigger a background agent from the Cursor sidebar, from Slack with an @Cursor mention, or by assigning a Cursor Agent to a Linear ticket.
• The cloud VM is ephemeral, so every dependency, env var, and setup command must be declared in files like .cursor/setup.sh before the run starts.
• Runs are billed from a shared credit pool based on token usage, so tightly scoped prompts and batched reviews keep parallel agent costs predictable.
• Most failed runs trace to expired GitHub tokens, broken setup scripts, under-specified prompts, or stuck long-running steps, and each has a direct fix.

A Cursor background agent is a cloud-hosted coding agent that runs your task in Cursor's remote environment, works on its own branch, and hands the result back as a pull request, without your terminal open. This guide walks the full lifecycle: trigger, environment, branch, PR handoff, plus troubleshooting for failed runs.

What is a Cursor background agent and how does it differ from normal Cursor chat?

A Cursor background agent is a cloud-hosted coding agent that works asynchronously in a remote environment while you do something else. You hand it a task, it clones the repo, works on its own branch, and comes back with a diff or a pull request. Normal chat and composer modes run locally in your editor, and you sit there waiting on the agent between prompts.

The difference is who waits. In chat, you are the loop: read output, queue the next prompt, repeat. A background agent breaks that loop, which is what makes running several at once practical. Cursor's docs describe these agents as operating in isolated cloud environments, with Slack and Linear as trigger points (Cursor docs on background agents).

That asynchronous model is the foundation for everything else in this guide, including how parallel runs are orchestrated with tools like Aerunit.

How do you start a background agent in Cursor step by step?

There are three ways to trigger a Cursor background agent: from the sidebar inside the editor, from Slack, or from a Linear ticket. All three end in the same place, a cloud VM with your repo cloned, an agent working on a branch, and eventually a PR. The differences are in what context each trigger carries and who can fire it.

Triggering from the Cursor sidebar

Open the agent panel (the tab icon in the right sidebar), sign in to Cursor.com if this is your first background run, and type your prompt into the composer. Before you hit send, three controls matter:

• Repository: pick the repo, or paste a public GitHub URL.
• Branch: choose an existing branch or let the agent create one.
• Terminal setup: commands the agent should run before starting, like pnpm install or starting a dev server.

Hit send and the run appears in the panel with a live status. You can close Cursor entirely; the agent keeps working and you get a notification when the PR is ready to review the diff.

Triggering from Slack or Linear

Mention @Cursor in any Slack channel and type your prompt. The agent replies in-thread with status updates and a PR link, so a teammate can kick off a run without opening the editor. The Linear path matters more for teams: connect Linear in your Cursor dashboard, then assign a Cursor Agent to a ticket. The agent reads the ticket's title, description, and acceptance criteria as its prompt, works on the issue's branch, and posts the PR back to the ticket.

That last detail is the whole point for a small team planning work in Linear. The ticket stops being a description for a human and becomes a spec for a machine: scope written once, executed by an agent, with the PR attached to the same ticket for review. If your acceptance criteria are thin, the run will be thin too, so write tickets the way you would brief a contractor. A fuller walkthrough of each trigger and its settings lives at Aerunit's Cursor background agents guide.

Where do background agents run and what environment do they get?

Each background agent runs in its own cloud VM, not on your laptop. When you launch one, Cursor clones your repository into an isolated machine, so the agent works on a clean copy of your code while you keep coding locally. Every run gets its own environment, which is why you can fire off several agents at once without them tripping over each other's working trees.

Machine setup and dependencies

The VM starts from a base image, then applies your repo's setup: it reads configuration files like .cursor/setup.sh or existing scripts to install dependencies and get the project into a buildable state. Anything your agent needs at runtime (a database, an env var, a CLI tool) has to be installed or declared in that setup, because the machine is ephemeral and nothing persists between runs. Each agent run consumes credits based on model usage and compute, per Cursor's docs. For teams juggling many parallel runs, tools like Aerunit queue and route work across agents so environments stay busy while you review the diffs.

How does a background agent hand off work via branch or pull request?

A Cursor background agent never touches your local checkout. It creates its own branch, commits there, pushes, and either opens a pull request or leaves the branch ready for you to turn into one. You review the diff on GitHub like any other PR.

Branch and PR conventions

The agent generates a branch name and, if you ask, a draft PR with a summary of what it changed. You can steer this in the prompt: "branch off main, name it fix/session-expiry, open a draft PR" gets you a predictable handoff. Without instructions you get a generic branch name and whatever title the agent infers. Teams that care about CI triggers or branch protection rules should pin the naming convention in the prompt or a repo-level rules file.

Reviewing the diff

When the agent finishes, you get a per-file diff plus its summary of the changes. Read the diff, not the summary: the summary is the agent grading its own homework. If the task touched several files, check whether the changes are complete against your acceptance criteria before merging. For a fuller lifecycle walkthrough, see Cursor background agents.

What can and cannot a Cursor background agent do?

A background agent can read your repo, edit files, run terminal commands, open a branch, and hand off work as a pull request, and you can send follow-up messages to steer it mid-run. Cursor's docs confirm the branch/PR handoff and follow-up behavior (Cursor docs).

What it cannot do is anything requiring your machine or your presence: no local-only tooling, no databases on localhost, no interactive debugging session where you step through code together. It runs in an isolated cloud environment, so anything bound to your laptop is invisible to it.

That constraint pushes the real work upstream: writing stories with explicit acceptance criteria. Vague prompts like "fix the auth bug" fail quietly. "Change the token refresh in auth.ts so expired tokens return 401, verified by the existing test suite" gives the agent a finish line.

The same honesty applies to us: Aerunit queues and reviews work for these agents, but it cannot fix a badly scoped story for you.

Why did my background agent fail and how do I fix it?

Common failure modes and fixes

Most failed runs fall into four buckets. Match the symptom, apply the fix, re-run.

Symptom	Likely cause	Fix
Run dies immediately with an auth error	Expired or revoked GitHub token	Reconnect the GitHub integration in Cursor settings, then re-trigger the agent
Environment setup fails or hangs	Broken install script or missing dependency in the setup commands	Reproduce the setup locally in a clean worktree; fix the script before re-running
Run stuck with no activity for 20+ minutes	Long build step, network call, or a prompt waiting on a decision the agent cannot make	Cancel the run, check logs for the last completed step, split the task into smaller scoped work
PR touches files outside the task scope	Under-specified prompt or missing repo guardrails	Add explicit file paths and acceptance criteria to the prompt; use a .cursorignore or branch rules to fence off protected directories

The stuck-run case is the one that costs the most, because polling burns tokens while you wait. If the same task type fails repeatedly, the problem is usually your prompt or environment, not the model: write down the acceptance criteria, name the files in scope, and make the setup script idempotent so a retry starts from a known state.

How much does running Cursor background agents cost?

Background agents run on usage-based billing, not a flat fee. Each run consumes credits based on the tokens the agent uses while it works, and those credits draw from your team's shared pool rather than an individual seat. That matters when you run several agents at once: six parallel runs on separate branches burn roughly six times the tokens of one, and polling a stuck agent for status costs credits too.

Two practical controls keep the bill predictable. First, scope each task tightly so the agent doesn't wander through files it doesn't need. Second, check what permissions the agent actually has before launch, since a run that can reach every private repo will read more and spend more; Cursor documents how GitHub integration and repository access work in its docs.

One honest caveat: Cursor does not publish a per-run cost estimate, so your first week of parallel usage is effectively a measurement period. Track credits per task type, then budget from observed numbers rather than guesses.

How do you run several background agents in parallel without becoming the bottleneck?

The agent is rarely the slow part. The slow part is the routine around it: queuing the next prompt, checking whether the diff matches the acceptance criteria, deciding what to launch next. Run six agents off Linear tickets and you spend your day as the glue between steps.

Three patterns help. First, scope each story so an agent can finish it in one pass: one branch, clear acceptance criteria, no cross-cutting refactors. Second, batch your reviews instead of polling each run; polling burns tokens and your attention. Third, keep a queue of well-scoped work so finished agents get replaced without you re-planning mid-afternoon.

Aerunit, our own tool, sits here: it pulls Linear stories into a queue for Cursor Cloud Agents, tracks what each run touched across repos, and bills from a team credit pool. Honest scoring against the criteria above: it assumes Linear and Cursor specifically, so teams on other trackers or other agents are out of scope, and it adds a layer between you and the PR that some solo developers will not want. Conductor, Devin, Agentastic, Factory, and Orgabot occupy the same category; pick by which tracker and agent stack they assume.

FAQ

Do Cursor background agents work with private repositories?

Yes. The agent clones your private repo into its cloud VM using the GitHub integration connected to your Cursor account. Access depends on the permissions you grant that integration, so a run can only reach repositories your token allows. If an agent fails with an auth error on a private repo, reconnect the GitHub integration in Cursor settings and re-trigger the run.

Can I follow up on a running background agent mid-task?

Yes. You can send follow-up messages to a running agent to steer it, correct course, or add context without restarting the run. This works from the agent panel in the editor or from the Slack thread where the run was triggered. Treat follow-ups like comments on a draft: specific instructions mid-run beat a full re-run with a rewritten prompt.

Do background agents work without Cursor open?

Yes. The agent runs on a cloud VM, not in your editor process, so you can close Cursor entirely and the run continues. You get a notification when the pull request is ready. The Slack and Linear triggers make this practical: a teammate can launch a run from a ticket and never open the editor at all.

How do background agents compare to Devin or Conductor?

They occupy the same category: asynchronous coding agents that work on a branch and hand off a pull request. The differences are in the surrounding stack, which tracker and editor each tool assumes, how runs are queued and billed, and how much layer sits between you and the PR. Pick by which issue tracker and agent stack your team already runs, then trial the workflow on one real task.