Guide · Cursor Cloud Agents

Cursor background agents: run more of them in parallel

Background agents can build, test, and ship while you do something else — but only if something keeps them fed. A practical guide to how they work, where to start them, and what it takes to keep a fleet busy with Linear as the control tower.

Mio Nilsson, creator of AerunitBy · Last updated

Cursor background agents working in parallel, illustrated in prismatic light
Fundamentals

What is a Cursor background agent?

First, the name: Cursor's docs say "Cloud Agents were formerly called Background Agents." Same product, new name — we use both in this guide. [3] A background agent is a coding agent that runs for a long stretch of time away from your laptop: the task moves to the cloud, and an agent carries it from start to finish without interruption, then reports back with proof that the work is done. [1]

Each one runs on its own dedicated virtual machine with a full development environment — your repository, dependencies, secrets, and network access. The agent plans the task, edits code, runs commands, and tests its work over minutes or hours, and it keeps going whether or not your machine is even online. [1] The VM is sandboxed and isolated from your local machine, and you control which repositories, secrets, and network access an environment gets. [1]

When the work is done, the agent opens a pull request — and shows its work. As it runs, it attaches screenshots, videos, and log references to the PR so you can validate changes without checking out the branch. [1] Cloud Agents can even drive their own desktop and browser, clicking through UI flows to verify that what they built actually works before pushing. [2]

Getting going

Five ways to start one

You can kick off a Cursor Cloud Agent from wherever you already work: [3]

01

In Cursor Desktop

Select Cloud by the agent input and hand it the task.

02

On the web or iPhone

Start and manage agents from Cursor Web (cursor.com/agents) or Cursor for iOS.

03

From where the work lives

Mention @Cursor in Slack, on a GitHub or Bitbucket issue or PR, or assign it a Linear issue.

04

With Automations

Run agents on a schedule (cron) or on events from GitHub, GitLab, Slack, Linear and webhooks.

05

From your own code

Start and manage agents programmatically with the API.

Automations are documented separately. [4] Before anyone can start an agent from a repository, a Cursor account admin connects source control: GitHub (Cloud and Enterprise Server), GitLab (Cloud and Self-Hosted), Bitbucket Cloud, or Azure DevOps. [3]

The real problem

Why running many is the hard part

The headline feature is easy to miss: you can run as many agents as you want in parallel, and none of them need your local machine to be connected. [3] Parallel is the whole point. A single background agent is a nice convenience; five running at once is a step change in how much ships per week.

But parallel agents change what the bottleneck is. The agents can do the coding around the clock — what they can't do is decide what's worth doing, in what order, and whether the work is actually done. Every agent you add consumes more of your attention at exactly the moments you're busiest: scoping the next task, reviewing a just-finished PR, spotting an agent that drifted off course. Run enough of them unmanaged and you spend your day shuttling between dashboards instead of driving the product.

There's a second, quieter failure mode: quality. An agent running unattended for an hour will happily build the wrong thing beautifully if the instruction was vague. With one agent, you notice. With ten, vague instructions quietly become ten wrong pull requests.

And those wrong pull requests cost real money. "Cloud Agents are charged at API pricing for the selected model… a larger context window can increase token usage and costs." [3] Parallelism multiplies that bill — so a vague story isn't just wasted review time, it's tokens spent building the wrong thing, several times over.

So the skill that matters with background agents isn't starting them — Cursor made that one mention away. It's feeding them. The teams that get the most out of parallel agents are the ones that can write work that's sharp enough to run unsupervised, and keep sight of every running agent without hovering over any of them. How many you can actually keep up with is mostly a review-capacity question.

Field notes

Practices that keep a fleet healthy

Write the story before you dispatch

Give each agent a clear scope and acceptance criteria, not a vibe. A sharp story with a definition of done runs unsupervised; a fuzzy one comes back wrong.

Keep the queue in one place

Plan in a tracker like Linear so you always know what's queued, what's running, and what's blocked — not scattered across Slack threads and terminal tabs.

Let agents pick up their own work

Once your stories are good enough, agents can be kicked off straight from the issue they belong to — in Linear, Slack, or GitHub — instead of you copy-pasting prompts one by one.

Watch for drift, not just completion

An agent that runs for two hours on the wrong problem costs more than one that finishes fast on the right one. Check for scope drift early, not just at the PR.

Trust artifacts, verify the edges

Agents attach screenshots, videos, and logs to their PRs — use them to review quickly without checking out every branch, and dig in only where it matters.

Use multi-repo environments when work spans services

For tasks that touch frontend, backend, and shared libraries in one run, a multi-repo environment lets one agent see and change the whole picture.

One note on that last practice: multi-repo environments let a single agent work across separate frontend, backend, infrastructure, or shared-library repositories and open pull requests in each repo it changes. [3] But even the best multi-repo environment works one task at a time — deciding what the architecture-level story should be, across all those repos, is still your job. For how to write it, see our guide to stories for coding agents.

The obvious question

Cursor already integrates with Linear — why add more?

Fair question. You can assign a Linear issue to @Cursor and a Cloud Agent picks it up, [5] and Automations can start agents from GitHub, Linear or Slack events. [4] Cursor is a very good engine. What it doesn't do is decide what to run, or in what order — it runs whatever issue you give it, when you give it.

That's the gap Aerunit fills. Think of Cursor as the engine and Aerunit as the dispatcher: it makes the issue worth running, sends it when it's ready to run, and sends review findings back to the same agent session to fix.

Where we come in

Where Aerunit fits

On top of Cursor's own Linear integration and Automations, Aerunit adds four things:

  • It writes the stories. You describe the work; Aerunit reads every repository the story touches and proposes Linear issues with scope, acceptance criteria and non-goals — a parent story plus one sub-issue per repo for cross-repo work.
  • It dispatches in dependency order. Aerunit follows Linear's blocks / blocked-by relations, so when a PR merges, the issues it was blocking go to Cursor Cloud Agents automatically — no dispatching by hand.
  • It reviews every PR. When an agent opens a pull request, Aerunit runs a code review and sends the findings back to the same agent session to fix — so the agent that wrote the code is the one that fixes it.
  • It shows the whole fleet. One list of every running Cloud Agent session, each linked to its Linear issue — message several at once, archive finished ones.

Engine: Cursor

Runs each task in its own cloud VM and opens the pull request.

Dispatcher: Aerunit

Writes the story, sends it when its blocker merges, reviews the PR.

Quick answers

Common questions

How many Cursor background agents can I run at once?

As many as you want in parallel — they run in their own VMs and don't need your machine connected. Two practical limits remain: cost, because Cloud Agents are charged at API pricing for the selected model and every parallel agent adds to that; and review, because every agent hands you a pull request to check. [3]

Cursor already has a Linear integration and Automations — why Aerunit?

Cursor is the engine: assign a Linear issue to @Cursor and an agent runs it, or trigger runs from events with Automations. Aerunit is the dispatcher on top: it writes the stories (across repos), follows Linear's blocking relations so the next slice starts when its blocker merges, reviews every agent PR automatically and sends findings back to the agent, and shows all running sessions in one list, each tied to its Linear issue. [5] [4]

Do background agents run on my computer?

No. Each Cloud Agent runs on a dedicated virtual machine in the cloud with your repository, dependencies, secrets and network access — sandboxed and isolated from your local machine. You can close your laptop and check the result later. [1]

How do I know what the agent actually did?

Agents attach screenshots, videos and log references to the pull request so you can validate the work without checking out the branch. You can also take control of the agent's remote desktop to try the software yourself. [2]

Can one background agent work across several repositories?

Yes. Multi-repo environments let a single agent inspect the full workspace, make coordinated changes across frontend, backend, infrastructure or shared-library repos, and open a pull request in each repo it changes. [3]

Aerunit

Keep the agents busy. You do the thinking.

Sign-up is open — create an account and start with pay-as-you-go credits. No subscriptions, and teams share one credit pool at no extra cost.

Create account