Cursor Cloud Agents are Cursor agents that run in isolated Ubuntu VMs in Cursor’s cloud instead of on your laptop: each one clones your repo, works on its own branch, can build and test the code, and hands off through a pull request (Cloud Agents, Security overview). They were formerly called Background Agents and need Premium or higher, Teams, Enterprise or a legacy paid plan; Free and Plus do not include them (Cloud Agents).
Applies to: Cursor Cloud Agents, Cursor docs and Models & Pricing page as of November 15, 2026. Last checked: November 15, 2026.
On this page
What you need before the first run
| Requirement | What the docs say |
|---|---|
| Plan | Premium and higher, Teams, Enterprise, or a legacy paid plan. Free and Plus don’t include Cloud Agents (Cloud Agents) |
| Source control | A Cursor account admin connects GitHub (Cloud and Enterprise Server), GitLab (Cloud and Self-Hosted), Bitbucket Cloud or Azure DevOps first (Cloud Agents) |
| Your own Git account | Each user connects their own account on top of the org install; an agent can only reach repos that user could already reach (Security overview) |
| Repo permissions | Read-write access to the repo and any dependent repos or submodules (Cloud Agents) |
| Spend limit | Cursor asks you to set one when you first start using Cloud Agents (Cloud Agents) |
There is one exception to the repository rule: Start from scratch in the repository picker runs an agent in a draft Origin repository that Cursor creates for it. That route needs a plan that includes both Cloud Agents and Origin, so again not Free or Plus (Cloud environment setup).
Where you can start a cloud agent
Cursor lists seven entry points (Cloud Agents):
| From | How |
|---|---|
| Cursor desktop | Select Cloud in the dropdown under the agent input |
| Web | cursor.com/agents on any device; on Android, install it as a PWA from Chrome |
| Cursor for iOS | Start and manage agents in the app |
| Slack | @cursor command |
| GitHub or Bitbucket | Comment @cursor on a GitHub PR or issue, or on a Bitbucket PR |
| Linear | @cursor command |
| API | The Cloud Agents API |
Every run follows the same path: Cursor provisions a VM, clones the authorized repo, the agent works and streams progress and artifacts back, then it pushes its branch and opens a pull request, ready for review unless you ask for a draft. Idle VMs are hibernated and then deleted on lifecycle timers (Security overview).
Set up the environment first
Cursor calls environment setup “the most important step to improve the effectiveness of your cloud agents”: an agent that cannot run tests or reach your services cannot check its own work (Cloud environment setup). There are two ways to do it:
- Agent-driven setup (recommended). Start it from the Cloud Agents dashboard or the Agents Window, connect your Git provider, pick repos and give the secrets it needs. The agent installs dependencies, verifies the code and saves the environment after a successful Build. Cursor says this takes less than 10 minutes.
- Manual setup with a Dockerfile. Point
.cursor/environment.jsonat a Dockerfile for system packages, compiler versions or a different base image. Do notCOPYthe full project; Cursor checks out the right commit itself.
This is Cursor’s example .cursor/environment.json with a Dockerfile and an install script (Cloud environment setup):
{
"build": {
"dockerfile": "Dockerfile",
"context": ".."
},
"install": "pnpm install && ./custom_script.sh"
}
And the snapshot-based form, where the snapshot ID comes from the environments page of the dashboard:
{
"snapshot": "snapshot-20260212-00000000-0000-0000-0000-000000000000",
"install": "npm install"
}
The path rules trip people up. dockerfile and context are relative to the repo’s .cursor folder; ., ./ and .. are special-cased to mean the repository root; when context is omitted it defaults to .cursor. The install command runs from the project root (Cloud environment setup).
What goes in install, start and terminals
| Key | When it runs | Put here |
|---|---|---|
install | While Cursor creates a Build, before any agent starts | Dependency installs, code generation, compiled artifacts, warmed caches. It must be idempotent, because it runs for every Build |
start | After an agent boots from a Build | Services such as Docker (sudo service docker start) |
terminals | After start | App processes, run in a tmux session you share with the agent |
A Build keeps disk state only: running processes, exported shell variables and in-memory caches do not carry into the agent run. A failed Build does not replace the active one, so agents keep starting from the last good environment (Cloud environment setup).
Which configuration wins
Cursor resolves the environment per repository or repo group and takes the first match (Cloud environment setup):
- Your personal saved environment
- The team’s saved environment
.cursor/environment.jsonin the repository (single-repo runs only)
A committed environment.json is not used automatically by a saved environment. New environments start with the environment.json location set to None (skip environment.json); pick the repository that holds the file when you create the environment. Builds read the configuration from the default branch, so push config changes before starting an agent on a feature branch (Cloud environment setup).
Secrets, MCP servers, rules and hooks
Secrets. Add them in the Secrets tab of the Cloud Agents dashboard; agents get them as environment variables. They are injected when an agent starts, so an agent that is already running will not see a secret you just added: start a new one. Environment-scoped secrets reach only agents using that environment. For AWS, Cursor can assume an IAM role you name in a secret called CURSOR_AWS_ASSUME_IAM_ROLE_ARN, with STS credentials that expire after 1 hour (Cloud Agents, Cloud environment setup).
MCP servers. Personal servers are added from the MCP dropdown in cursor.com/agents; team admins add shared ones under Dashboard -> Plugins & MCPs. Cloud agents support HTTP and stdio servers, not SSE or mcp-remote. Cursor recommends HTTP, because the server configuration never enters the VM and tool calls are proxied through Cursor’s backend; a stdio server runs inside the VM, where the agent can read its config and environment variables (Capabilities). The MCP servers you use locally are in the MCP directory, and the Cursor mcp.json setup is in Best MCP servers for Cursor.
Rules and AGENTS.md. Cloud agents follow user rules, team rules and .cursor/rules/*.mdc files in the repo, and they read AGENTS.md (Best practices). Cursor suggests a dedicated section with a title such as Cursor Cloud specific instructions for cloud-only setup and test steps (Cloud environment setup). See Cursor rules, .mdc and AGENTS.md for the file formats.
Hooks. Command-based hooks in .cursor/hooks.json at the project root run in cloud agents; on Enterprise plans, team and enterprise-managed hooks run too. User hooks in ~/.cursor/hooks.json do not, because the VM has no access to your home directory, and no hook runs during early read-only exploratory turns (Hooks, Cloud Agents). Details and examples: Cursor hooks.
Security: commands run without asking
Warning
Cursor’s security overview says Cloud Agents auto-run terminal commands so they can iterate on tests without stopping for approval, which is more autonomous than the foreground agent: an attacker who plants instructions in content the agent reads could try to make it exfiltrate code to an external host. Cursor’s documented layers against this are network egress allowlists, Runtime Secrets that are redacted from transcripts and never reach the model,
.cursorignorefor sensitive paths, pull-request review before anything merges, and signed commits.
Network access has three modes, set by users, team admins or environment owners: Allow all network access, Default + allowlist, and Allowlist only (Settings). If your work does not need open internet access, the two allowlist modes are the ones Cursor’s security page points to.
Warning
The Team follow-ups setting lets teammates steer an agent that runs with the creator’s secrets. Cursor’s settings docs say a team member with limited permissions could use a follow-up to make the agent read environment variables, print secrets or push credentials elsewhere, and advise treating the setting like shared SSH keys. The safer choices are Disabled or Service accounts only.
What Cursor keeps, and for how long (Security overview):
| Data | Retention |
|---|---|
| Runtime workspace (the VM) | Recycled after the run goes idle; follow-up prompts refresh the timer |
| VM snapshots | Rolling 30 days of inactivity, then deleted; cannot be deleted on demand |
| Conversation state | Kept until you delete it (Delete Agent API); Enterprise can cap it with retention policies |
| Secrets and tokens | Kept until you remove them |
Cloud Agents run in Privacy Mode, and legacy Privacy Mode is not supported for them (Security overview). For Cursor’s wider security settings, see Is Cursor AI safe?.
What Cloud Agents cost
Cloud Agents draw on your plan’s usage like other agent work, at the selected model’s rate, and a larger context window can increase token use (Cloud Agents). On current plans, one weekly usage pool for Cursor’s own models is shared by Agent in the editor, the CLI, Cloud Agents, Grok Bot and the Grok apps; third-party models are billed at API list price from prepaid credit on Premium and above (Models & Pricing). On legacy request-based plans, Cloud Agents are priced at API rates plus the Max Mode upcharge against included requests (Cloud Agents).
| Plan (Models & Pricing) | Price | Included usage | Cloud Agents |
|---|---|---|---|
| Free | $0 | Limited | No |
| Plus | $8/mo | Base | No |
| Premium | $30/mo | 4x Plus | Yes |
| Super | $100/mo | 15x Plus | Yes |
| Ultra | $200/mo | 50x Plus | Yes |
| Teams | $30, $100 or $200 per seat/mo | Matches the seat’s tier | Yes |
| Enterprise | Custom | Pooled | Yes |
Older Pro, Pro+, Ultra, Start and Teams Standard or Premium seats are legacy plans that keep working as they are (Models & Pricing). Every Cursor plan we track is in the plans tracker.
When an agent will not start
Cursor’s troubleshooting list, in order (Cloud Agents):
- You are signed in and have connected GitHub, GitLab, Azure DevOps or Bitbucket.
- You have the repository permissions the agent needs.
- Your plan includes Cloud Agents (not Free or Plus).
- A secret is missing: check it is in the right team or workspace, then start a new agent, since running agents do not pick up new secrets.
- A teammate cannot open your agent: they must be in the same Cursor team, connect their own source control account and have access to the repo. Team membership alone does not grant access.





