When a Cursor team moves long agent tasks onto Cloud Agents, what defines each VM's environment, and what replaces the local approval prompts?
answer
- formerly Background Agents
- agent-led setup, snapshot or Dockerfile
- .cursor/environment.json wins first
- install per Build; start per run
- no Run Modes: secrets and egress
basics
~20 sA Cursor Cloud Agent boots an isolated VM from its environment's latest successful Build, defined by agent-led setup, a snapshot or a Dockerfile in .cursor/environment.json. Run Modes don't apply there: it runs every command itself, so secrets and network egress are the controls.
solid answer
~40 sCloud Agents (formerly Background Agents) run in isolated Ubuntu VMs, work on a separate branch and push it for handoff. The environment comes from agent-led setup (recommended), a saved snapshot, or a Dockerfile referenced from `.cursor/environment.json`; Cursor uses the repository's `.cursor/environment.json` first, then a personal saved environment, then a team one. `install` runs during each Build, ahead of time, while `start` and `terminals` run when each agent boots. Run Modes apply only to local agents: a Cloud Agent auto-runs every terminal command and never asks for approval. The controls move into the environment: secret types (`Environment Variable`, a `Runtime Secret` redacted as `[REDACTED]`, a `Build Secret` seen only by the Docker build) and network access, which is open by default and can be narrowed to **Default + allowlist** or **Allowlist only**.
code
json · 8 lines{
"build": {
"dockerfile": "Dockerfile",
"context": ".."
},
"install": "pnpm install",
"start": "sudo service docker start"
}go deeper
Recall that Cloud Agents, formerly Background Agents, run in a cloud VM, push a branch, and can be started with @cursor on a GitHub pull request or issue.
Explain the environment pieces: agent-led setup, snapshot or Dockerfile, the environment.json resolution order, and when install, start and terminals run.
Plan the move off laptops: no Run Modes in the cloud, internet open by default, which secret type each credential needs, and why a running agent misses new secrets.
Decide the team's egress and secret policy for unattended runs, trading agent capability against exfiltration risk once no human approves commands.
## What a Cloud Agent is A **Cloud Agent** is Cursor's agent running in an **isolated virtual machine in the cloud** instead of on your laptop. The docs record the rename: *Cloud Agents were formerly called Background Agents.* - Each run gets its own Ubuntu VM with a full development environment: cloned repositories, installed dependencies, secrets, startup commands and network access. - The agent clones the repository, works on a **separate branch** and **pushes it** for handoff, typically as a pull request with screenshots, videos and logs attached. - You start one by selecting **Cloud** under the agent input in Cursor, at cursor.com/agents, by commenting **`@cursor`** on a GitHub pull request or issue, from Slack or Linear, or through the API. - An account admin must connect source control first, and Cloud Agents need a paid plan. ## Where the environment comes from There are three ways to define the machine: - **Agent-led setup** (recommended): Cursor's agent installs dependencies, verifies the code runs and saves the environment after a successful Build. - **A saved snapshot**, referenced by its ID. - **A Dockerfile**, referenced from `.cursor/environment.json`. For a given repository Cursor uses the **first match**: 1. `.cursor/environment.json` in the repository 2. A personal saved environment 3. A team saved environment A **Build** is a bootable snapshot of the prepared machine. Cursor clones the repositories at their default branch, runs `install` to completion and saves the disk. New agents start from the latest successful Build, and a failed Build never replaces the working one. | Command | When it runs | Use it for | |---|---|---| | `install` | During each Build | Dependencies, code generation, warm caches; must be idempotent | | `start` | At each agent start | Docker, databases, tunnels | | `terminals` | At each agent start | App processes in `tmux` shared with the agent | Builds keep disk state only, so running services belong in `start` or `terminals`. Two more details shape what an agent sees: - **Freshness.** Default-branch runs start at the commit the active Build recorded. With **Update stale builds** on, agents pull the latest default-branch code when the Build is older than the **Staleness threshold**, 24 hours by default. Feature-branch runs check out the requested branch on top of the Build. - **Multi-repo environments.** One environment can clone several repositories, so a single agent can change a frontend and a backend together and open a pull request in each. ## Secrets | Type | Behaviour | |---|---| | **Environment Variable** | Visible to the agent; for non-sensitive values such as flags or public URLs | | **Runtime Secret** (formerly Redacted Secret) | Loaded as an environment variable, but replaced with `[REDACTED]` in tool results, the transcript, commits and commit messages; still visible to a person using the VM's terminal | | **Build Secret** | Available only to the Docker build, never to the running agent | Secrets are injected **when an agent starts**, so an agent that is already running does not see a secret added later. For cloud roles, the docs prefer short-lived **OIDC tokens** minted from a local socket over long-lived keys. ## What replaces the approval prompts Locally, **Run Modes** decide what Agent may run without asking. They **do not apply to Cloud Agents**: the agent runs inside its own machine, auto-runs all terminal commands and never asks for approval. The security page names the cost: a prompt-injected agent could try to upload code somewhere. The controls therefore sit around the VM: - **Network access.** The agent has internet access by default. The modes are **Allow all network access**, **Default + allowlist** (Cursor's default domains plus yours) and **Allowlist only**, set per user, per saved environment or as a team default; Enterprise admins can lock it. - **Secret types**, chosen as above, and environment-scoped secrets for credentials only one environment should hold. - **Hooks** from the repository's `.cursor/hooks.json`, which still run in the cloud; user-level hooks in `~/.cursor/hooks.json` do not. - **Review of the pushed branch**, since nothing was approved along the way. ## Handoff traps - **Move to Cloud** carries the conversation, not your uncommitted edits; the agent starts from a clean Git state on the remote. - `.cursor/environment.json` changes are built from the **default branch**; push them there for team-wide effect. - Legacy Privacy Mode is not supported; switch to Privacy Mode first.
- You added an API key in the Cursor dashboard's Secrets tab, but the Cloud Agent that is already running cannot see it. Why?Secrets are injected when an agent starts, so agents already running don't pick up new ones; start a new agent. Also check scope: secrets are workspace- or team-scoped, and user secrets are not available during Builds, only once an agent starts.
- A developer used Move to Cloud mid-task in Cursor, and the Cloud Agent doesn't see their latest edits. What happened?Move to Cloud does not snapshot local uncommitted changes. The Cloud Agent starts from a clean Git state on the remote repository and carries over only the conversation history and context. Commit and push the work before moving if the agent should start from it.
- Which Cursor Cloud Agent secret type keeps a database password out of the transcript and commits while the agent still uses it?A **Runtime Secret**, formerly called a Redacted Secret. It is loaded as an environment variable, but its value is replaced with `[REDACTED]` in tool results, the transcript, commits and commit messages. A person working in the VM's terminal can still see it.
- Cloud Agents ask before each terminal command, just like the local Agent
- A Cloud Agent has no internet access until you allowlist domains
- Move to Cloud uploads your uncommitted changes to the VM
- A personal saved environment overrides a committed .cursor/environment.json
- A Runtime Secret is hidden even from people using the VM's terminal
- Background Agents and Cloud Agents are two separate Cursor features