Core Summary

Cursor Cloud Agents are asynchronous coding agents that run in remote development environments. Cursor formerly called them Background Agents. A run clones authorized repositories into an isolated environment, executes tools and tests, produces review artifacts, pushes a branch, and can open a draft pull request.

The useful mental model is a remote contributor with bounded authority, not an autonomous teammate you can trust by default. The product supplies execution infrastructure and handoff surfaces; your team still owns task scope, repository permissions, network policy, secrets, acceptance tests, review, merge controls, rollback, and incident response.

Contents

Key Takeaways

  • Background Agents is the former product name; current Cursor documentation calls the remote service Cloud Agents.
  • Cursor-hosted runs execute in dedicated cloud VMs, not local Git worktrees.
  • Environment configuration, saved Builds, network policy, and credential type are part of the release identity.
  • Internet access is available by default unless you configure a stricter egress mode.
  • Runtime-secret redaction limits where values are copied; it does not remove the secret from the process environment.
  • A draft pull request is a handoff artifact, not evidence that the change is safe to merge.

What a Cloud Agent Is

A Cursor Cloud Agent is a coding agent that runs in a remote environment instead of on the developer's laptop. It can be started from Cursor clients and connected integrations, then continue after the local device disconnects.

Cursor documents three deployment boundaries that should not be collapsed:

Boundary Where tools execute Important consequence
Foreground/local Agent developer-controlled machine or editor sandbox local credentials and files may be in scope
Cursor-hosted Cloud Agent dedicated remote VM managed by Cursor code, environment, secrets, network, and retained run data cross a cloud boundary
Self-Hosted Machines customer-managed worker infrastructure tool execution moves, but the broader Agent service and data flow still require review

The old article treated "Background Agent" as a broad umbrella for local worktrees, cloud VMs, and SSH. That is no longer an accurate product description. Cursor's current naming page says Background Agents were renamed to Cloud Agents, and the Cloud Agent documentation defines them by remote execution.

For a product-neutral comparison of coding runtimes, use the AI coding tools evaluation guide. This page stays focused on Cursor's current Cloud Agent operating contract.

How a Run Moves from Task to Pull Request

A Cloud Agent run is a chain of externally visible state transitions:

flowchart LR A["Task and repository selection"] --> B["Provision isolated environment"] B --> C["Clone authorized repositories"] C --> D["Install and start environment"] D --> E["Edit, test, and collect artifacts"] E --> F["Push separate branch"] F --> G["Open draft pull request"] G --> H{"Human and CI gates pass?"} H -- "No" --> I["Revise, hold, or discard"] H -- "Yes" --> J["Merge through repository policy"]

Cursor documents that source-control access has two layers: an administrator connects and scopes the provider application, then each user connects an account and can start runs only for repositories that user can access. This is useful containment, but it is not enough by itself. A repository token that permits a push does not authorize a production deployment, database migration, secret rotation, or cross-repository policy change.

The handoff should include:

  • exact base commit and branch;
  • environment and Build identity;
  • changed-file inventory;
  • commands run and their exit status;
  • screenshots, videos, or logs needed to review behavior;
  • unresolved warnings and skipped checks;
  • external effects attempted or completed;
  • rollback and reconciliation instructions.

Cursor signs Cloud Agent commits according to its security documentation. Signature verification proves the commit was produced through the declared signing identity; it does not prove code correctness, reviewer approval, or provenance of every dependency.

How to Build a Reproducible Environment

Cloud Agents use isolated Ubuntu environments with cloned repositories, installed dependencies, startup commands, secrets, and network access. Cursor supports agent-led setup, saved environments, and Dockerfile-based setup referenced by .cursor/environment.json.

The current environment resolution order for Cursor-hosted Cloud Agents is:

  1. repository .cursor/environment.json;
  2. a personal saved environment;
  3. a team saved environment.

Self-Hosted Machines do not read .cursor/environment.json for environment setup, so test that execution path separately instead of assuming cloud configuration applies.

A minimal repository-owned configuration can identify a Docker build and deterministic install command:

json 
{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "go mod download && go test ./..."
}

This is a configuration shape, not a complete production recipe. Keep these rules:

  • Make install idempotent because every Build may run it over previously prepared disk state.
  • Put dependency installation, generation, and compilation in install.
  • Put long-running services in start or terminals; a Build captures disk state, not live processes or exported shell variables.
  • Do not COPY the repository into the Docker image; Cursor manages checkout.
  • Inspect the environment and Build version attached to the run before accepting its evidence.
  • Keep project behavior instructions in reviewed AGENTS.md or Cursor Rules, not in an untracked dashboard note.

The AGENTS.md guide explains how to keep repository instructions scoped and testable.

How to Scope a Useful Task

A useful asynchronous task is small enough to verify and complete enough to hand off. Write a task contract with:

Field Question
base Which commit and repositories define the starting state?
scope Which files or packages may change?
outcome What observable behavior must be different?
invariants What must remain unchanged?
checks Which commands and reviewers prove acceptance?
authority Which tools, secrets, networks, and external writes are allowed?
stop rule When should the Agent stop and ask rather than guess?
delivery What branch, PR, artifacts, and risk notes are required?

Parallel runs can increase candidate throughput, but they also multiply review load, compute cost, branch conflicts, and dependency pressure. Use separate tasks only when their write sets and acceptance evidence are independent. For competing implementations, compare them under the same base revision, environment, model setting, budget, tests, and evaluator.

Which Security Controls Matter

Cloud execution changes the threat model because repository content, package scripts, web pages, issues, and tool results can influence an Agent that automatically runs commands.

Repository and identity

  • Grant the source-control application only the repositories required for the workload.
  • Preserve the triggering user's access boundary and apply normal branch protection.
  • Prefer short-lived OIDC federation for cloud roles instead of long-lived access keys.
  • Treat multi-repository environments as one combined blast radius.

Secrets

Cursor exposes three distinct categories:

Type Runtime exposure Appropriate use
Environment Variable visible to the Agent process non-sensitive flags and public configuration
Runtime Secret environment variable, redacted from model-facing outputs and commits credentials that the process must use
Build Secret available only to Docker build steps private registries and build-time credentials

Runtime Secrets remain visible to a human with terminal access to the environment. Redaction is a recording control, not a hardware enclave or proof that arbitrary executed code cannot read the value.

Network and data

Cursor documents that Internet access is available by default and can be changed to Default plus allowlist or Allowlist only. Use the narrowest mode that supports the task. Prefer exact artifact-host entries over broad wildcards, and audit every new destination.

The service also distinguishes runtime workspaces, snapshots, conversation state, and credentials. Its current security documentation says conversation state is retained indefinitely by default, while snapshots expire after 90 days of inactivity. The Delete Agent API removes a run's transcript and artifacts but does not delete snapshots on demand. Treat these as provider policies to verify against your plan and regulatory requirements, not as assumptions that local deletion propagated everywhere.

For the general threat model, see Prompt Injection and AI Agent Tool Security.

How to Gate the Handoff in Go

The merge decision should be deterministic even when the Agent's narrative is persuasive. The following Go program rejects a handoff that cannot be tied to its intended base, environment Build, required checks, review, and rollback evidence:

go 
package main

import (
	"errors"
	"fmt"
)

type Handoff struct {
	BaseCommit        string
	EnvironmentBuild  string
	ChangedFiles      int
	RequiredChecksRun bool
	SecurityReviewed  bool
	RollbackReady     bool
	UnknownEffects    int
}

func validate(h Handoff) error {
	switch {
	case h.BaseCommit == "" || h.EnvironmentBuild == "":
		return errors.New("missing release identity")
	case h.ChangedFiles == 0:
		return errors.New("empty change set")
	case !h.RequiredChecksRun:
		return errors.New("required checks did not run")
	case !h.SecurityReviewed:
		return errors.New("security review missing")
	case h.UnknownEffects > 0:
		return errors.New("external effects need reconciliation")
	case !h.RollbackReady:
		return errors.New("rollback is not ready")
	default:
		return nil
	}
}

func main() {
	handoff := Handoff{
		BaseCommit:        "8d9f0ab",
		EnvironmentBuild:  "build-42",
		ChangedFiles:      6,
		RequiredChecksRun: true,
		SecurityReviewed:  true,
		RollbackReady:     true,
	}
	fmt.Printf("release_ready=%t err=%v\n", validate(handoff) == nil, validate(handoff))
}

This gate does not inspect code quality by itself. It makes missing evidence explicit so repository checks and human review cannot be replaced by a fluent completion message.

How to Evaluate Cloud Agents

Evaluate the complete workflow against a human or deterministic baseline:

  • accepted task outcome, not lines changed;
  • first-pass and final CI success;
  • critical invariant violations;
  • review findings by severity;
  • unrelated diff and rollback effort;
  • elapsed time and human attention;
  • model, compute, tool, and review cost;
  • secret exposure, denied egress, and unauthorized-effect attempts.

Use repeated trials because model behavior varies. Segment results by task type, repository, language, change size, and risk tier. A high aggregate pass rate can hide failures in migrations, authorization, concurrency, or generated code.

The coding-agent comparison guide provides a controlled trial design. The Agent Harness Evaluation Guide covers trajectories, graders, and fault injection.

Common Failure Modes

Failure Why it happens Required response
stale Build dependency or generated state differs from the base commit rebuild and rerun the same checks
hidden setup failure install passed partially or a service never became ready assert postconditions, not only exit code
secret exfiltration untrusted content influences a command with network access restrict egress, reduce credentials, review the trace
cross-repository drift one repository changes without compatible dependents use one versioned multi-repo contract and coordinated tests
misleading artifact screenshot or summary omits a failing state require raw check status and reproducible commands
duplicate external effect retry follows a timeout after the first write committed use idempotency keys and reconciliation
retention mismatch team assumes deletion semantics that the provider does not offer document each data class and verify deletion behavior

Frequently Asked Questions

Are Cursor Background Agents now called Cloud Agents?

Yes. Cursor's current documentation uses Cloud Agents and lists Background Agents as the former name. Preserve the old phrase only as a search alias or historical reference.

Can Cloud Agents work across multiple repositories?

Yes, when the selected environment contains the authorized repository group. Treat the group as one release boundary: record each base commit, run cross-repository compatibility checks, and open reviewable pull requests for every changed repository.

Does an isolated VM make a Cloud Agent safe?

No. VM isolation limits some host and cross-run risks, but the Agent can still read repository data, execute package scripts, use credentials, and reach allowed networks. Least privilege, egress controls, runtime-secret handling, policy checks, branch protection, and review remain necessary.

How should a team delete Cloud Agent data?

Map the provider's controls to each data class. Cursor documents an Agent deletion API for conversation state and artifacts, a rolling inactivity window for snapshots, and separate credential deletion. Verify the current policy and your plan before assigning sensitive work.

What is the best first Cloud Agent task?

Choose a low-consequence task with a deterministic oracle: a focused test addition, a mechanical migration with contract tests, or a documentation correction with link checks. Avoid the first trial being a production hotfix, secret rotation, or irreversible data change.