Cursor background agents are now called Cloud Agents. They are Cursor agents that run in isolated virtual machines in the cloud instead of on your laptop: each one clones your repo, works on a separate branch, can build and test the code, and pushes the result back for you to review, often as a pull request.
Cursor's docs put the rename in one line: "Cloud Agents were formerly called Background Agents." This guide uses the current name and is based on Cursor's Cloud Agents documentation read on 24 October 2026.
How do Cursor Cloud Agents differ from the local agent?
The local agent in the editor works in your checkout, on your machine, and by default asks before it runs terminal commands. A cloud agent works on its own VM with a full development environment: cloned repos, installed dependencies, secrets, startup commands and network access.
That gives you a few things the local agent cannot:
- Parallel work. Cursor says "You can run as many agents as you want in parallel," and they do not need your machine to stay online.
- Verification. Because each agent has its own VM, it can build, test and use the changed software, including controlling a desktop and browser.
- Artifacts. Agents attach screenshots, videos and logs that show what changed and how they checked it. You can also take over the agent's remote desktop to try the change yourself, then hand control back.
- Multi-repo tasks. An environment can include several repos, such as frontend and backend, and the agent can open pull requests in each repo it changes.
The tradeoff is autonomy. Cursor's security page notes that the cloud agent "auto-runs all terminal commands, letting it iterate on tests," unlike the foreground agent, which asks for approval.
Where can you start a Cursor cloud agent?
First, a Cursor account admin connects source control: GitHub (Cloud and Enterprise Server), GitLab, Bitbucket Cloud or Azure DevOps. Then you can start agents from:
| Where | How |
|---|---|
| Cursor desktop | Select Cloud in the dropdown under the agent input |
| Web | cursor.com/agents on any device |
| iOS | The Cursor iOS app (Android users can install cursor.com/agents as a web app) |
| Slack and Linear | The @cursor command |
| GitHub or Bitbucket | Comment @cursor on a GitHub pull request or issue, or a Bitbucket pull request |
| API | The Cloud Agents API |
You can also choose Start from scratch in the repository picker to begin without a repo. Cursor then creates a draft Origin repository for the work, which needs a plan that includes both Cloud Agents and Origin.
How do you set up a cloud agent environment?
Cursor calls environment setup "the most important step to improve the effectiveness of your cloud agents." An agent that cannot run your tests cannot check its own work. The setup docs describe two ways to do it.
Agent-driven setup (recommended). From the Cloud Agents dashboard or the Agents Window in the desktop app, connect your source control, pick repos and supply the environment variables needed to install and run the code. The agent installs dependencies in a shared terminal you can watch, and Cursor saves the environment after a successful Build. Cursor says this takes less than 10 minutes.
Manual setup with a Dockerfile. For system packages, specific compilers or a different base image, point .cursor/environment.json at a Dockerfile:
{
"build": {
"dockerfile": "Dockerfile",
"context": ".."
},
"install": "pnpm install && ./custom_script.sh"
}
Do not COPY the whole project in the Dockerfile; Cursor checks out the right commit itself.
A few keys in environment.json matter most:
installruns while Cursor creates a Build, in the background, so dependencies are ready before an agent starts. It must be idempotent because it runs for every Build.startruns after an agent boots from a Build. Use it for things likesudo service docker start.terminalsare long-running app processes, such as a dev server, that run in atmuxsession you share with the agent.
Builds keep disk state only, so running processes and exported shell variables do not carry over; start services in start or terminals. If a Build fails, agents keep starting from the last successful one.
Cursor picks the environment for a repo in this order: your personal saved environment, then a team saved environment, then .cursor/environment.json in the repo (single-repo runs only).
How do you give cloud agents context and rules?
Cloud agents read AGENTS.md, and Cursor recommends a dedicated section titled something like "Cursor Cloud specific instructions" for cloud-only setup and test steps. See the AGENTS.md guide for the format.
They also follow Cursor rules at three levels: user rules from Cursor Settings, team rules from the dashboard, and repo rules in .cursor/rules/*.mdc. Cursor's best practices page suggests committing project skills for tasks the agent finds hard, such as debugging a specific service, and treating the agent as "a smart, but low-context human developer."
For tools, cloud agents can use MCP servers configured for your team, over HTTP or stdio, with OAuth where needed. You manage them from the MCP dropdown at cursor.com/agents. The Cursor MCP guide covers the local side.
How do secrets work in cloud agents?
Add secrets in the Secrets tab of the Cloud Agents dashboard. Cursor offers three types:
| Type | Visible to the agent? | Best for |
|---|---|---|
| Environment Variable | Yes | Non-sensitive config such as flags or public URLs |
| Runtime Secret | Loaded as an env var, but redacted as [REDACTED] in tool output, transcripts, commits and commit messages |
API keys and passwords |
| Build Secret | No, only the Docker build | Private package registry tokens |
Secrets are injected when an agent starts, so agents already running will not see new ones. For cloud roles, Cursor recommends short-lived OIDC tokens over long-lived keys, and it can also assume an AWS IAM role you configure.
Do hooks run in cloud agents?
Yes, with limits. Cloud agents run command-based hooks from .cursor/hooks.json in your repo, plus team and enterprise hooks on Enterprise plans. User hooks in ~/.cursor/hooks.json do not run, because the VM cannot see your home folder, and Tab hooks, workspaceOpen, sessionStart, sessionEnd and the MCP execution hooks are not available. The Cursor hooks guide lists what each event does.
What does it cost and which plans include it?
Cursor's troubleshooting section says you need "a plan that includes Cloud Agents: Premium and higher, Teams, Enterprise, or a legacy paid plan. Free and Plus don't include them."
Cloud Agents use your plan's usage like other agent work, at the selected model's rate. A larger context window can raise token use. You are asked to set a spend limit when you first start using them. Check Cursor's models and pricing page for current rates rather than relying on numbers copied elsewhere.
What should you know about security?
From Cursor's Secrets and Network page:
- Your code runs in isolated VMs on Cursor's AWS infrastructure.
- The agent has internet access by default. You can set network egress controls to limit which domains it can reach.
- Because commands auto-run, prompt injection could trick an agent into sending code somewhere it should not go. Egress limits and Runtime Secrets reduce that risk.
- Commits are signed and show as Verified on GitHub. On GitHub, they are authored as
Cursor Agent <cursoragent@cursor.com>, with the person who started the agent added as aCo-authored-bytrailer when Cursor can look them up. - Cloud Agents work with Privacy Mode, but not with the legacy Privacy Mode setting, which you need to switch from first.
Teammates on the same Cursor team can open an agent's URL to view the run, but only if they also have access to the repository.
Keep the instructions your agents rely on
Cloud agents do better with good AGENTS.md sections, rules and skills, and those tend to be rewritten in every repo. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own, with search and tags, so the versions that work are easy to find and reuse.