Cursor Cloud Agents (Formerly Background Agents): Setup, Limits and Review

Cursor background agents are now called cloud agents. They are Cursor’s agent running in an isolated virtual machine in Cursor’s cloud instead of on your laptop: it clones your repository, works on a separate branch, runs your tests, pushes the branch and opens a draft pull request for a person to review. Getting good results depends on three things you set up once: an environment the agent can build and test in, secrets it can use without printing, and a review step that nothing skips. This guide covers each, then where you can start a run from, how to watch it, and what the limits are.

If you want Cursor’s cloud agents compared with GitHub Copilot’s, that is in GitHub Copilot agent vs Cursor agent. This post is about using Cursor’s.

Background agents, cloud agents: what changed

Only the name, as far as your setup goes. Cursor’s cloud agents documentation↗ (opens in a new tab) ends with a one-line naming history: cloud agents were formerly called background agents, and the old documentation address now redirects there. The dashboard, the settings and the help pages all use the new name, so search for “cloud agent” when a menu item seems to have moved. The install script was also renamed: the dashboard used to call it the update script.

Before the first run

• A paid Cursor plan. Cloud agents are billed at API pricing for the model you pick, and you are asked to set a spend limit the first time.
• Source control connected by an admin: GitHub, GitLab, Bitbucket Cloud or Azure DevOps. Each person who starts agents then connects their own account.
• Read-write access to the repository, and to any dependent repositories or submodules. An agent can only reach repositories the person who started it could already reach.

Set up the environment first

An agent that can write code but cannot run your tests hands back guesses. Cursor’s own docs call environment setup the most important step, and give you two ways to do it.

• Agent-driven setup, which Cursor recommends. Start it from the Cloud Agents dashboard or the Agents Window, pick the repositories, give it the variables and secrets it needs, and watch it install dependencies in a shared terminal. It saves the environment once the code is verified and a first Build succeeds.
• A Dockerfile, for system packages, pinned compiler versions or a different base image. You point to it from .cursor/environment.json and never COPY the whole project in; Cursor checks out the right commit itself.

Commit .cursor/environment.json so the whole team starts from the same machine. Cursor’s cloud environment setup page↗ (opens in a new tab) lists the order it resolves environments in: the file in the repository first, then a personal saved environment, then a team one.

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "pnpm install && pnpm codegen",
  "start": "sudo service docker start"
}

• install runs when Cursor prepares a Build, in the background, not each time an agent starts. It must be idempotent, because it runs on every Build and may run over disk state it prepared before. Put dependency installs, code generation and compilation here.
• start runs after an agent boots from a Build. Services that must stay alive, such as Docker, a database or a tunnel, go here, not in install, because a Build keeps disk state only: processes and exported variables do not survive.
• The dockerfile and context paths are relative to .cursor; the values ., ./ and .. mean the repository root.
• A failed Build does not replace the active one. Agents keep starting from the last good environment while you read the logs.

Cloud agents read AGENTS.md. Cursor suggests a section titled something like “Cursor Cloud specific instructions” for what only applies in the cloud: which service to start for which task, how to log in to the app, which tests need a network. Cursor rules examples has sample rule files that travel with the repository to the cloud as well.

Secrets without leaks

Add secrets in the Secrets tab of the Cloud Agents dashboard, not in a committed .env file. They reach the agent as environment variables, and you choose a type for each.

• Environment variables: plain values the agent can read, such as a test API base URL.
• Runtime secrets, previously called redacted secrets: still loaded as environment variables, but, per Cursor’s secrets and network page↗ (opens in a new tab), their values are replaced with [REDACTED] in tool results, the chat transcript, commits and commit messages. Anyone using the agent’s terminal can still see them.
• Build secrets: available only to the Docker build, for a private package registry, and never exposed to the running agent.
• Environment-scoped secrets: available only to agents using one environment, useful for staging credentials or a multi-repository setup.

Two practical points. Secrets are injected when an agent starts, so an agent already running will not see one you just added; start a new run. And for cloud roles, Cursor recommends short-lived OIDC tokens minted from the agent’s machine over long-lived access keys.

Starting a cloud agent

• Cursor desktop: choose Cloud in the dropdown under the agent input. Move to Cloud hands a local conversation over, but it starts from a clean checkout of the remote branch, so commit or stash first; uncommitted edits do not travel.
• The web and your phone: cursor.com/agents, the iOS app, or on Android the web app installed from Chrome.
• Slack: mention @Cursor with the task. It tries to work out the repository, branch and model from the message; inline options make them explicit.
• GitHub: comment @cursor on a pull request or issue. On Bitbucket Cloud, comment on a pull request. Linear works the same way, and there is an API.
• The terminal: in Cursor’s command-line agent, start any message with & and the conversation is pushed to a cloud agent. The CLI overview↗ (opens in a new tab) documents this as Cloud Agent handoff.

# Slack
@Cursor repo=acme/shop branch=main autopr=false Fix BUG-214: the basket total ignores the discount code

# Cursor CLI, mid-conversation
& fix BUG-214, add a regression test, and open a PR

A cloud agent works from the prompt, the repository and its instructions files. Write the prompt as a task: the outcome, the files in scope, and the check that proves it is done. How to write a task for an AI agent has the template.

Watching a run

• The Agents Window, cursor.com/agents and the iOS app show the same runs as they happen. On cursor.com/agents, Send now steers a running agent without stopping it; the message is picked up at its next tool call.
• Artifacts: agents attach screenshots, videos and logs showing how they checked their work. Each agent has a full desktop, and you can take control of it to try the change yourself, then hand it back.
• Subscriptions: ask the agent to “open a PR and keep CI green” and it waits for CI results and review comments, then carries on in the same conversation. On Teams plans, agents also try to fix GitHub Actions failures on their own pull requests; comment @cursor autofix off to stop that on one.
• Sharing: send a run’s address to a teammate on the same Cursor team who can also access the repository. Viewing is read-only unless an admin turns on team follow-ups.

Be careful with team follow-ups. A follow-up directs an agent that runs with the original creator’s secrets, so a teammate with less access could use it to read what they could not read themselves. Cursor’s settings page says to treat it like a shared SSH key.

Reviewing and merging

Cursor’s cloud agent security overview↗ (opens in a new tab) describes the hand-off: the agent pushes its branch and opens a draft pull request, and nothing merges until a person reviews it. Every agent commit is signed and shows as verified, so agent-authored changes are attributable in your Git history.

1. Read the task first, then the diff. Does the change do what was asked, and only that?
2. Look at the artifacts, then run the tests yourself or check that CI ran the ones that matter.
3. Ask for fixes in the same run: a follow-up or an @cursor comment on the pull request keeps the context.
4. Mark it ready and merge like any other pull request, under your branch protection rules.

An automated review, such as Bugbot, is a second opinion, not the check. Verifying AI-generated work has the routine, and AI agents for PR review covers where review bots fit.

Limits and privacy

• Resources: each agent runs on a default machine with limited memory and CPU. Enterprise teams can ask for more.
• Autonomy: cloud agents run terminal commands without stopping for approval. That is what lets them iterate, and it is why Cursor’s security page singles out prompt injection: instructions planted in something the agent reads could try to send code elsewhere. Restrict network access to a default list plus your allowlist, or to your allowlist only.
• MCP: HTTP and stdio servers work, SSE does not. Prefer HTTP: its configuration and tokens never enter the agent’s machine, while a stdio server runs inside it with its environment. MCP security risks covers the wider picture.
• Hooks: project hooks in .cursor/hooks.json run in the cloud; your personal hooks in your home folder do not, because the machine cannot see it.
• Privacy: cloud agents run in Privacy Mode, and legacy Privacy Mode is not supported. Conversations are kept until you delete them through the API, and machine snapshots are deleted after 90 days of inactivity.

Where the task itself lives

A cloud agent started from Slack at six in the evening leaves its record in three places: a Slack thread, a run on one person’s account and a draft pull request. None of them says why the work was wanted or whether anyone checked it. Put the task on a board the agent reads first and writes back to. Add fenbs as an HTTP server from the MCP menu at cursor.com/agents; Cursor supports OAuth for cloud MCP servers, per user, so you sign in in the browser and no token is pasted into the machine. Then one line in AGENTS.md: read the task with fenbs_get_item before starting, write the approach into its plan, and when the pull request is open, comment its link and set testStatus and testNotes to what was actually run. If the owner has pressed “Let AI do this” on a task, fenbs_next_approved_task hands the agent the most urgent one, inside the limits written on it. Every change is recorded under the assistant’s name and yours.