Based on Anysphere’s official docs, checked November 12, 2026

Cursor Cloud Agents (formerly Background Agents): setup, access and limits

Cursor Cloud Agents are coding agents that run in isolated virtual machines in Cursor’s cloud, with a full development environment, instead of on your laptop. Cursor’s own docs say Cloud Agents were formerly called Background Agents, which is why both names still appear in search. This guide follows Cursor’s Cloud Agents documentation, the Cloud Environment Setup page, the Cloud Agent security overview and the “What are background agents?” help article, all checked November 12, 2026. It covers how to start an agent, why environment setup matters, which source-control providers are supported, how billing and plan access are described, and the limits Cursor documents around secrets, sharing and hooks. We have not run Cloud Agents hands-on, and we do not invent per-task prices. Where Cursor gives a plan list or a billing rule, we quote it as a vendor statement from the page checked today.

1. 1. Check that your plan includes Cloud Agents

   Cursor’s Cloud Agents troubleshooting docs say you need a plan that includes Cloud Agents: Premium and higher, Teams, Enterprise, or a legacy paid plan. Free and Plus do not include them. If you cannot start an agent, check the plan first, then login and source-control connection, before you debug the environment. This is Cursor’s stated entitlement, not a guess about a regional promotion.

2. 2. Connect source control before anyone starts an agent from a repo

   Before anyone can start a cloud agent from a repository, a Cursor account admin needs to connect source control for the account. Cursor documents GitHub (Cloud and Enterprise Server), GitLab (Cloud and Self-Hosted), Bitbucket Cloud, and Azure DevOps. To start without a repository, use Start from scratch. Cloud agents clone the repo and work on a separate branch, then push changes for handoff. You need read-write privileges to your repo and to any dependent repos or submodules. Team membership alone does not grant a teammate access to a run: Cursor also verifies that the viewer has access to the repository the agent worked in, and that they have connected their own source-control account under Integrations.

3. 3. Start the agent from the surface you already use

   Cursor lists several ways to kick off a cloud agent: the Cursor iOS app; Cursor Web at cursor.com/agents on any device; Cursor Desktop, by selecting Cloud in the dropdown under the agent input; Slack, with the @cursor command; GitHub or Bitbucket, by commenting @cursor on a pull request or issue (Bitbucket on a pull request); Linear, with the @cursor command; and the Cloud Agents API. On Android, Cursor points you to cursor.com/agents in Chrome and to installing a Progressive Web App; the native iPhone and iPad app is documented separately. The help article on background agents matches this set: in Cursor, select Cloud by the agent input; on the web or mobile, go to cursor.com/agents; in Slack, GitHub or Linear, mention @Cursor. You can also run them on a schedule or from events with Automations. Do not treat a comment in an unrelated tool as a supported trigger unless Cursor’s docs list it.

4. 4. Invest in the environment, not only the prompt

   Cursor’s guidance is unusually direct: agents are only as capable as the environments they run in, and not setting up a development environment is like not giving your engineers a computer. The environment is meant to look like a laptop setup: cloned repos, installed dependencies, secrets, startup commands and network access. You can configure environments with agent-led setup from the Cloud Agents dashboard, a saved snapshot, or a Dockerfile in .cursor/environment.json. Both of the main setup paths let you specify an install script; Cursor runs it while creating a Build so dependencies are ready before an agent starts. Builds prepare each environment in the background. The Cloud Agents dashboard shows which environment and Build an agent used; on the agent page, you can hover over the repository name to inspect the environment for that run. Use the install script for work Cursor can prepare ahead of time, such as installing dependencies, generating code, compiling artifacts and warming disk caches.

5. 5. Add secrets, network limits and MCP the way Cursor documents them

   Cursor manages VM provisioning, isolation, snapshots, startup, artifacts and capacity. You can add secrets, restrict outbound domains, connect to private networks with Tailscale or a similar client, and use private connectivity for supported source-control paths. Secrets are added at cursor.com/dashboard/cloud-agents, are workspace or team scoped, and are injected when an agent starts; an already running agent will not pick up a secret you just added, so start a new agent after changing secrets. Cursor recommends the Secrets tab rather than relying on a snapshot of .env.local, even though a snapshot can save .env.local files if you include them during snapshot creation. Cloud agents can use MCP servers configured for your team, added and managed through the MCP dropdown on cursor.com/agents. Both HTTP and stdio transports are supported, and OAuth is supported for servers that need it. Cursor also includes a built-in Cursor Cloud MCP for run diagnostics, including transcripts, run events, environment details and setup logs. Do not paste production credentials into the prompt in order to “just test” a connection.

6. 6. Review the branch, artifacts and desktop before you merge

   Cloud agents produce merge-ready pull requests with artifacts that demo the change: screenshots, videos and logs, so you can see what changed and how the agent verified its work. Pull requests open ready for review unless you ask for a draft. You can also take control of the agent’s remote desktop to test the software in the remote environment without checking out the branch locally, then release control back to the agent. Send the agent’s URL to a teammate on the same Cursor team only if they also have repository access; viewing is read-only unless a team admin has enabled team follow-ups. Hooks from .cursor/hooks.json in the repository do run on cloud agents, which keeps formatters, audit scripts and policy checks active in the cloud. On Enterprise plans, team hooks and enterprise-managed hooks also run. Hooks do not run during early exploratory turns in a read-only environment; they start once the agent has a writable environment. User-level hooks from ~/.cursor/hooks.json are not available, because cloud VMs do not have your local home directory. Some hooks are IDE-specific and do not apply.

Billing and usage, as Cursor describes them

Cursor says Cloud Agents use your plan’s usage like other agent work, at the selected model’s rate. You can select the context window size for supported models, and a larger context window can increase token usage and costs. You will be asked to set a spend limit when you first start using them. On legacy request-based plans, Cursor says they are priced at API rates plus the Max Mode upcharge against your included requests. This guide does not invent a per-task dollar amount or a hidden included-allowance for Cloud Agents beyond those rules.

If an agent run is not starting, Cursor’s checklist is: confirm you are logged in, confirm source control is connected, confirm repository permissions, and confirm you are on a plan that includes Cloud Agents. If a teammate cannot open your agent, they must belong to the same Cursor team, connect their own source-control account, and have access to that repository.

The Cloud Agents API is in public beta

Cursor documents a Cloud Agents API for starting and managing cloud agents and their environments programmatically. The v1 API is in public beta, and Cursor says the APIs may change before general availability. Authentication accepts Basic and Bearer methods; you generate a user API key from Cursor Dashboard → API Keys, or use a service account API key. Repositories can come from any source-control provider Cursor supports, including self-hosted hosts. This page does not reproduce the full endpoint list; use Cursor’s API reference for the current schema.

Because the API can start an agent that clones a repository and opens a pull request, treat the key like any other credential that can write to your repos. Do not embed it in a prompt, a client-side app or a public workflow log.

Why the old “background agent” name still matters for search

People still search for “cursor background agent” because that was the previous product name. Cursor’s help article “What are background agents?” now answers that question by saying: in Cursor, these are Cloud Agents. A useful page has to say both names, then use the current one. The product is the same isolated-VM workflow: a long-running coding agent that can leave your laptop, work for minutes or hours, and come back with a branch, a pull request and artifacts.

If you are comparing this to a local Cursor agent, the important documented differences are where the commands run (a Cursor-managed VM, not your machine), that your laptop does not need to stay online, that you can run many agents in parallel, and that local user-level hooks are not available on the VM. Multi-repo environments are supported when a task spans separate frontend, backend, infrastructure or shared-library repositories.

Tips

• Check plan entitlement first: Cursor says Free and Plus do not include Cloud Agents.
• Connect source control, and grant read-write access, before you debug a run that never starts.
• Treat environment setup as the main quality lever; a clever prompt cannot replace missing tests or dependencies.
• Add secrets in the dashboard and start a new agent after you change them; running agents do not pick up new secrets.
• Do not merge a cloud-agent pull request until you have reviewed the artifacts, and the remote desktop if you need to click through the change.

Next steps

Sources

• https://cursor.com/docs/cloud-agent · checked 2026-11-12
• https://cursor.com/docs/cloud-agent/setup · checked 2026-11-12
• https://cursor.com/docs/cloud-agent/security · checked 2026-11-12
• https://cursor.com/help/ai-features/background-agents · checked 2026-11-12
• https://cursor.com/docs/cloud-agent/api/endpoints · checked 2026-11-12