Cursor Cloud Agents on a shared backlog

Cloud Agents run in isolated Ubuntu VMs

Cursor renamed Background Agents to Cloud Agents in Cursor 2.0, released October 29, 2025. The feature first appeared as a preview in 0.50 on May 15, 2025. It became generally available in 1.0 on June 4, 2025.

Each agent gets an isolated Ubuntu VM with a full desktop environment, running on Firecracker microVMs in a separate AWS account. The agent clones the repo, works on a separate branch and pushes its changes. Through the API, it pushes to an auto-generated cursor/ branch unless workOnCurrentBranch is set, while autoCreatePR opens a pull request.

Cursor 3.0, released April 2, 2026, removed Cloud Agents from the editor and added the Agents Window in their place. You can start a run at cursor.com/agents, in the Agents Window or from the iOS app. Slack, Linear and Jira can each start a run. A GitHub issue or a comment on GitHub or Bitbucket can start a run. The CLI starts a run when you prepend & to a message. The API can start runs. Bugbot autofix spawns a Cloud Agent.

Cloud Agents require temporary code storage, so the legacy Privacy Mode is unsupported. You can take control of the remote desktop to inspect the work in its running environment. An agent can attach screenshots, videos and log references to its pull request, as described in Cursor’s capabilities docs.

Every run starts with a prompt

The Cursor Agents API, released as a public beta on April 29, 2026, creates agents, sends follow-up runs, streams a run over SSE and cancels it. Its default rate limit is 20 requests a minute. Cursor lists webhooks as coming soon.

Cursor documents no tool that lets an agent pull its own next task from a backlog. Its Subscriptions let an agent end its turn and wake when an event arrives, such as a Linear issue being created or changing state. A subscription can last at most 180 days.

Cursor Projects, introduced September 10, 2026, adds a coordinator that plans work and delegates it to agents. The coordinator does not write code itself. It runs as many agents in parallel as the work needs.

The environment separates installation from startup

Cursor reads the environment from .cursor/environment.json in the repo, then a personal saved environment, then a team saved environment, according to Cursor’s setup docs.

The install command must be idempotent because it runs while Cursor creates a Build. After boot, Cursor runs start and the configured terminals in a tmux session shared by you and the agent.

Cloud Agents have internet access by default. They auto-run all terminal commands. Teams can restrict the network to an allowlist, so check that policy before depending on a remote service.

Cursor distinguishes environment variables the agent can see, runtime secrets redacted as [REDACTED], and build secrets used only by the Docker build. Secrets are injected when an agent starts. A running agent keeps the values it started with, according to the security and network docs.

HTTP MCP stays outside the VM

Cloud Agents support HTTP and stdio MCP servers. Cursor proxies HTTP server configurations through its backend, so they never reach the VM. Retasc’s Authorization header stays out of the VM. stdio servers run inside the VM.

SSE and mcp-remote are unsupported for Cloud Agent MCP, even though the Agents API can stream a run over SSE. Retasc exposes streamable HTTP at https://mcp.retasc.com/mcp. Configure that endpoint as an HTTP server.

Admins configure team servers under Dashboard, Plugins & MCPs. Personal servers come from the MCP dropdown at cursor.com/agents. OAuth authorization is per user even when the server is shared with the team.

An authentication failure reports mcp_auth_error. Cursor skips that server’s tools and continues the run, so a running agent does not establish that Retasc connected. Check the authentication result before asking it to pull work, following Cursor’s API reference.

A hosted key connects the Cloud Agent to Retasc

Create a Retasc key for the hosted agent with retasc key mint --org-id <id> --project-id <id> --hosted. The --hosted flag marks the key for a runner with no local install.

Retasc prints the key once. Store it in the hosted runner’s secret store. Every Retasc request must carry Authorization: Bearer <api key>.

An admin adds a team server under Dashboard, Plugins & MCPs. You add a personal server from the MCP dropdown at cursor.com/agents. For either setup, use https://mcp.retasc.com/mcp with the hosted key. For an API-created agent, pass the key through an mcpServers entry.

For the local editor, run npx @retasc/cli@latest bind in the folder you want to connect. It asks for browser approval once if you are not signed in. It gives the folder an agent key. It wires the MCP server. Then start or restart the local agent. The Cloud Agent uses the hosted key instead.

Parallel runs still need a shared claim

Cursor’s Cloud Agent docs say you can run as many agents as you want in parallel. A Cursor staff forum reply dated March 9, 2026 gives a concurrent limit of 8, with higher limits on Pro+ and Ultra. Those sources do not state the same limit.

Only one run can be active on an agent. Sending another run to a busy agent returns 409 agent_busy. That limit applies to an individual agent, so it does not prevent several agents from receiving overlapping prompts about the same backlog issue.

Cursor’s docs describe no claim, lease or lock between Cloud Agents working on an issue or branch. An agent that pulls through next_issue gets an issue no other agent holds. The claim is one server transaction.

Subagents share their parent’s checkout by default and can overwrite each other’s changes, according to Cursor’s subagent docs. Retasc’s next_batch can hand an orchestrator issues that do not depend on each other for a wave of subagents. Those issue assignments do not change Cursor’s shared checkout.

A standing prompt lets the run keep pulling

A standing prompt can keep the same run pulling work. “Call next_issue and work only on the issue it claims. Record checkpoints with what is done, what is next and the gotchas. Send finished work to review with its branch, PR or commit. Pull again. When nothing is ready, Retasc returns how many issues are blocked, claimed, held, waiting for sign-off or in other people’s lanes. Report those counts. Then stop the run.”

next_issue claims the highest effective-priority issue that is unblocked and unclaimed. A claim is one server transaction. Two agents can never hold the same issue.

Blocked work is never handed out. When a blocker closes, its dependents join the queue. A blocker inherits the urgency of the work it holds up, so a chore blocking an urgent feature jumps the queue. Every issue an agent creates must declare what it is blocked by, or state in one line why it depends on nothing. The refusal suggests similar or mentioned open issues to link.

A claim is a 30-minute lease, renewed by heartbeat or checkpoint. No Retasc CLI runs beside this hosted agent to provide the local setup’s automatic renewal every 10 minutes, so the agent must renew through MCP. A checkpoint gives the lease a full 30 minutes from when it lands while preserving the handoff.

The next runtime gets the checkpoint

Friday’s Claude Code session can leave a checkpoint for Monday’s Cloud Agent, recording the work already done and where the next agent should continue. When renewal stops because a process dies, a laptop closes or a terminal is killed, the reclaimer returns the issue to the queue in its owner’s lane. Before sending work to review, the agent must say where it is through a branch, PR or commit unless it already left a checkpoint.

The same person’s agents are offered that issue first, on any runtime. If nobody returns for 7 days, it goes back to the shared pool. Every claim through next_issue, claim_issue or next_batch hands over the last checkpoint, including what is done, what is next and the gotchas.

A next_issue claim also includes the issue’s body. After a lapse, the claiming agent gets the checkpoint’s author and time plus the reclaim count. Review goes to a different person’s agent, and the server refuses to let whoever sent the work to review claim or accept that review.

Actions belong to the person whose key the agent uses and the runtime it reports, with the human identity coming from GitHub or Google sign-in rather than anything the agent says. The Dash lists every agent, including cursor, claude-code and codex, with its runtime, issue and minutes left on the lease. Analytics shows each shipped issue’s Retasc fees, team hours and cost of work redone after a lapse.

Cursor starts the run and Retasc supplies the work

Retasc does not start, schedule or host Cloud Agents. Cursor’s API, Slack or an automation starts the run, including the initial prompt that tells the agent to pull from Retasc. Retasc never sees its VM.

Cursor ends a run as FINISHED, ERROR, CANCELLED or EXPIRED. Cancellation is terminal, so continuing requires a new run on the same agent, which picks up its conversation and workspace state. Idle VMs are hibernated and then deleted on Cursor’s lifecycle timers.

You pay for the calls a Cloud Agent makes to pull work or renew its claim. A dispatch through next_issue, next_batch or claim_issue costs $0.007. A checkpoint costs $0.005. A heartbeat costs $0.0001. Billing is per action with no seats and free, unlimited members.

Questions about Cursor background agents

Mint a hosted key for the Cloud Agent and run the command in your local folder so cloud and local agents pull from the same queue. A new org gets $10 of usage at signup, no card.