Guide

Cursor Cloud Agents: a practical guide to remote coding agents

By Atlas AI Resources · Published October 23, 2026 · How we make these guides

Cursor Cloud Agents are coding agents that run in their own virtual machine in Cursor’s cloud instead of on your laptop. You hand one a task, it works on a separate branch, and the work comes back as a pull request you review. This page sums up what Cursor’s official docs say about starting them, setting up their environment, getting work back, and keeping them safe. Then it adds our own advice: a first-week plan, a task brief, and a review checklist you can copy.

Everything below is based on Cursor’s public Cloud Agents docs as we read them on October 23, 2026. Cloud Agents were formerly called Background Agents, so older posts may use that name. Features, plans, and limits change, so check the linked docs before you rely on any detail.

1. What a Cloud Agent is

Per the docs, a Cloud Agent uses the same agent basics as Cursor’s local agent but runs in an isolated VM with a full development environment: cloned repos, installed dependencies, secrets, startup commands, and network access. That changes what it can do:

• Parallel work. The docs say you can run as many as you want in parallel, and they don’t need your computer to stay online.
• It can run what it builds. Each agent has a desktop it can drive with mouse and keyboard, so it can start a dev server, click through the app, and check its change before pushing.
• Tools. Cloud Agents can use MCP servers configured for your team, and they run command-based hooks from .cursor/hooks.json in your repo.
• Several repos at once. A multi-repo environment lets one agent change a frontend, backend, and shared library together and open a PR in each repo it changes.

2. Where you can start one

Before anyone can start a Cloud Agent on a repository, a Cursor admin has to connect source control for the account (GitHub, GitLab, Bitbucket Cloud, or Azure DevOps, per the docs). After that, the docs list these starting points:

• Cursor desktop: choose Cloud in the dropdown under the agent input. The Agents Window also lets you move an agent between local and cloud.
• Web: cursor.com/agents, on any device. On Android, the docs suggest installing it from Chrome as a web app.
• Cursor for iOS: a native iPhone and iPad app for starting agents, following them live, and reviewing pull requests.
• Slack: mention @cursor with a prompt. The agent reads the whole thread for context, and you can set options inline, for example (simplified from the docs’ example, which also sets env= and model=) @Cursor branch=dev autopr=false Fix the login bug.
• GitHub or Bitbucket: comment @cursor on a GitHub pull request or issue, or on a Bitbucket pull request.
• Linear: use the @cursor command.
• API: start and manage agents from your own code.

Cursor’s Automations also run Cloud Agents on a schedule or on events such as a new pull request. Our guide to scheduling AI agent routines covers that side.

3. Set up the environment before the first real task

The docs call environment setup “the most important step” for getting good results: an agent that can write code but can’t run tests or reach the services it needs can’t check its own work. The options, as the docs describe them:

• Agent-driven setup (recommended by Cursor). Start it from the Cloud Agents dashboard or the Agents Window, pick repos, and supply the env vars and secrets. The docs say this can take less than 10 minutes; Cursor saves the environment after a successful Build.
• Dockerfile (advanced). Point to it from .cursor/environment.json. Don’t COPY the whole project; Cursor checks out the right commit itself.
• Install script. The install command runs ahead of time while a Build is prepared. It must be idempotent. Long-running processes (databases, dev servers, tunnels) belong in start or terminals instead.
• AGENTS.md. Cloud Agents read it. The docs suggest a section titled something like “Cursor Cloud specific instructions” for cloud-only setup and test steps.
• Secrets. Add them in the dashboard’s Secrets tab; they show up as environment variables. They are injected when an agent starts, so agents already running won’t see new ones.

Cursor’s best practices page adds a useful test: if your repo is hard for a person to run and test locally, it will be hard for an agent too. It also suggests treating the agent as “a smart, but low-context human developer” and giving it context through skills, AGENTS.md, and rules.

4. How the work comes back

• A branch and a pull request. The agent clones your repo, works on a separate branch, and pushes it. Cursor’s security overview says it opens a draft pull request for a person to review before anything merges.
• Proof attached. Agents produce screenshots, videos, and logs and attach them to the PR, so you can see what changed and how the agent checked it.
• Hands-on testing. You can take over the agent’s remote desktop to try the change yourself without checking out the branch, then hand control back.
• Follow-ups. You can send more instructions to a running agent from the web, Slack, or the iOS app. Agents can also subscribe to events, such as review comments and CI results on their PR or a reply in a Slack thread, and pick the work back up when they arrive.
• CI fixes. The docs say Cloud Agents automatically try to fix failing GitHub Actions checks on PRs they create (currently on Teams), stop after 10 such follow-ups on a PR, and never auto-fix failures on commits a person pushed.

5. Security notes from the docs

The biggest difference from the local agent: Cloud Agents run terminal commands without stopping for approval at each step, so they can iterate on tests. Cursor’s security overview says plainly that this changes the risk model, because instructions planted in content the agent reads (prompt injection) could try to make it send code to an outside host. The layers the docs describe:

• Network egress. Internet access is on by default. You can switch to Cursor’s default domains plus your allowlist, or to your allowlist only, and Enterprise admins can lock that org-wide.
• Runtime Secrets. Secrets marked this way are stripped from the transcript, tool output, and commits and never reach the model.
• File exclusion. Paths in .cursorignore stay out of the agent’s context.
• Access is inherited, not widened. An agent can only reach repos the person who started it could already reach.
• Review before merge. Agents open draft PRs, and their commits are signed so agent changes are attributable.
• Team follow-ups. If admins let teammates send follow-ups to each other’s agents, the settings page warns that someone could steer an agent running with a more privileged person’s secrets. The docs compare it to sharing SSH keys.

Our guide on keeping AI agents safe from prompt injection covers why issue text, PR comments, and Slack threads should be treated as data, not orders.

6. Cost and plans

Per the docs’ billing section, Cloud Agents draw on your plan’s usage like other agent work, at the selected model’s rate. A larger context window can increase token use and cost, and Cursor asks you to set a spend limit the first time you use them. The docs’ troubleshooting section says Cloud Agents need a plan that includes them (Premium and higher, Teams, Enterprise, or a legacy paid plan) and that Free and Plus don’t. Check Cursor’s models and pricing page for current rates; we don’t quote prices here because they change.

7. Cloud or local: which to use

Cursor’s docs describe the local agent as asking for your approval before terminal commands by default, while Cloud Agents auto-run them inside an isolated VM. The security FAQ calls the cloud “a different risk profile, not a worse one.” Our rule of thumb:

• Use a Cloud Agent for well-scoped tasks with a clear finish line (a bug with repro steps, a small feature behind tests, a dependency bump), for several tasks in parallel, and for work you want to keep going while your laptop is closed.
• Stay local when you’re still figuring out what you want, when you want to approve each command, or when the task needs things only your machine has. (Cursor also offers self-hosted machines and a Remote Control mode for that last case; see the docs.)

Per the Agents Window docs, you can also move an agent from cloud to local to iterate, then back to the cloud.

Our advice

The checklists and templates in this section are our own, not Cursor’s. Adapt them to your repo.

Our advice: a first-week rollout

1. Day 1: set up one environment for one repo. Start one agent with a tiny, low-risk task (a typo fix or a one-file test) just to prove it can install, build, and run your tests.
2. Days 2–3: give it one real task type, such as bugs with clear repro steps. Review every PR yourself. Write down each thing you had to fix by hand.
3. Days 4–5: turn those notes into AGENTS.md lines, rules, or a skill, so the next run starts with that context.
4. Week 2: only then try parallel agents or a second task type. Add one at a time.

Our advice: a task brief template

• Goal: one sentence on the change (for example, “the login form shows an error instead of a blank page when the API times out”).
• Where: repo ____, base branch ____, files or area ____ to start from.
• Out of scope: don’t touch ____ (migrations, public APIs, other services).
• Done means: tests ____ pass, plus a new test for ____.
• Proof: attach a before/after screenshot or a short video of ____, and paste the test command and its output.
• If stuck: say what you tried and what’s blocking you; don’t guess at credentials or widen the scope.

Our advice: a PR review checklist

• Read the diff, not just the summary. A confident write-up and a green check are not the same as a correct change.
• Check the proof matches the ask. Does the screenshot or video show the actual scenario from the brief?
• Look for scope creep: unrelated files, new dependencies, changed config, or edits to tests so they pass.
• Send new evidence when you ask for a redo. Paste the failing log, a screenshot, or the exact line that’s wrong. “Try again” with nothing new tends to get the same result.
• Merge yourself. Keep a person as the final yes on merges, enforced by your repo’s branch protection (required reviews and checks), not by an instruction in a prompt.

Our advice: an environment and safety checklist

• Start with the “default + allowlist” network mode, and add domains as the agent actually needs them.
• Give the agent staging or test credentials, never production keys, and mark them as Runtime Secrets.
• Add sensitive paths to .cursorignore.
• Leave team follow-ups off unless you have a clear reason, and think about whose secrets each agent carries.
• If you use any automatic approval (for example Cursor’s PR Routing & Approval agent, which the Automations docs say can approve low-risk changes), start with one narrow class of change and keep required human review on everything else. An agent’s confidence is a recommendation, not permission.
• Judge the setup by PRs you actually merged and kept, and what each one cost, not by how many agents you launched.

If you also run Grok Bot

Some teams have a Grok Bot start and steer Cursor Cloud Agents for them. Our Grok Bot for engineering page summarizes one engineer’s setup, with a shared PR board and proof requirements. For running many agents on one goal with human review at the end, see parallel agent campaigns.

Useful public resources

Related: Grok Bot for engineering · Parallel agent campaigns · Keeping AI agents safe from prompt injection · Skills before routines · Scheduling AI agent routines · Internal tools with AI agents