Cursor Cloud Agents: repo vs environment

What a Cloud Agent actually is

When you run Cursor’s agent in the editor on your own machine, it works on the folder open in front of you. It sees your unsaved edits, your untracked scratch files, the API key you exported in your terminal an hour ago, and the CLI tool you installed by hand last spring. All of that is simply there, because it is your computer.

A Cloud Agent is a different machine, in a data centre, that you never log into. Cursor starts it from a base image, clones your repository into it, and runs an install script to get it into a usable state. Then the agent starts working — on that copy, not on yours.

If you have seen these called Background Agents, that is the same feature — Cursor’s documentation notes that Cloud Agents were formerly called Background Agents. The older name still turns up in blog posts and older screenshots.

What the agent boots from

Cursor’s documented sequence is: start from the environment’s base image, clone its repositories, and run install to completion. Three consequences fall directly out of that sentence, and they explain most of the confusion:

• It clones. A clone pulls what the remote has. Commits sitting only on your laptop, and files you never committed at all, are not on the remote — so they are not in the agent’s copy either. This is also why Cursor states that moving work to the cloud does not carry over your local uncommitted changes: the agent starts from a clean git state.
• Untracked and gitignored files are invisible. A local .env, a scratch fixture file, a downloaded dataset — if git does not track it, the clone does not contain it. This catches people constantly, because the file is right there in the editor while they are reading the agent’s “file not found.”
• Install runs every time an environment is built. Tools that exist on your machine only because you installed them once, by hand, months ago, must be installed by the install script instead — otherwise they simply are not present.

One subtlety worth internalising: builds are cached, and Cursor is explicit that a build preserves disk state only. Running processes, exported shell variables, and in-memory caches do not continue into an agent run. A service you started during setup is not still running when the agent begins work.

The file that defines the environment

The environment is configured by .cursor/environment.json at the root of your repository. A simple one looks like this:

{
  "install": "npm install",
  "start": "npm run dev",
  "terminals": [
    {
      "name": "dev server",
      "command": "npm run dev"
    }
  ]
}

The keys that matter:

There are three documented ways to define an environment: let the agent configure it interactively, boot from a saved snapshot, or build from a Dockerfile. The Dockerfile form looks like this:

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "pnpm install && ./custom_script.sh"
}

If your project needs a database, a specific runtime version, or a system package, the Dockerfile route is the one that stays reproducible. The interactive route is faster to start and harder to explain to a teammate six weeks later.

Secrets and environment variables

Nothing about your shell environment is ambient here. If a value reaches the agent, it is because it was explicitly injected. Cursor’s recommended path is the Secrets tab in Cursor Settings, managed through cursor.com; those values are exposed to the Cloud Agent as environment variables.

Local .env.local files included at snapshot-creation time are saved into the snapshot, but leaning on that is fragile: the values are frozen into the image, and rotating a key means rebuilding. Use the Secrets tab.

MCP inside a Cloud Agent

This is the part that surprises experienced users, because the behaviour genuinely differs from the desktop editor and it depends on the server’s transport.

• HTTP servers. Their configuration is never present in the Cloud Agent’s VM. The agent has no access to refresh tokens, headers, or other credentials, and tool calls are proxied through Cursor’s backend instead.
• stdio servers. These run inside the agent’s VM, so the agent does have access to the server’s configuration and environment variables — much like stdio servers in the desktop editor. Because they execute in the VM, Cursor cannot verify that a stdio server will run successfully until an agent is actually launched.

Practical reading: a stdio server that works on your laptop because a binary happens to be installed there will fail in a Cloud Agent unless your install script puts that binary in the image. An HTTP server that works locally will generally keep working, because the credentials never needed to be in the VM in the first place.

How to debug it properly

The failure mode to avoid is re-prompting the agent in the hope that better wording will conjure a missing file. Check the environment instead:

1. Read the Builds tab. It shows the prepared environment versions available to Cloud Agents, and lets you inspect logs, trigger a build, and pin or choose the active build. A setup step that failed quietly is visible here and nowhere in the chat.
2. Ask the agent to list the path. Have it run a directory listing inside its own environment rather than reasoning about what “should” be there. One command settles it.
3. Confirm the work is actually pushed. Committed but unpushed is the single most common version of this bug, and it looks identical to a broken agent from the chat window.
4. Check whether the tool is in the install script. If the agent cannot run something you use daily, the question is whether install puts it there — not whether the agent “knows about” it.

What to read next

The same repo-versus-environment split shows up in miniature across the rest of Cursor — see Cursor setup that survives updates for the surfaces overview. If a server is red inside or outside an agent, work through MCP server stuck red in Cursor, which covers the auth-scope distinction this page touches on. Grok Bot is a different computer again — persistent, shared across every Bot on your account, and not a clone of your repo — see Grok Bot: info, FAQ, and examples.