Cloud Agent Builds: Setup, Speed and Fallbacks

A Build is a ready-to-use copy of a Cloud Agent environment, prepared before any agent needs it. Cursor starts from your base image, clones every repository in the environment at its default branch, and runs the install command to completion. It then saves the disk state with the exact commit of each repository. A successful Build becomes active, and Cursor keeps warm copies of it ready.

The point is to take repeated setup out of every agent start. Cursor reports that its internal environments now boot 10 times faster and reach the first token 3 times faster. Those are Cursor's own measurements from the August 13, 2026 launch, not a promise for your repository. A project with a short install has less time to save than one with a large dependency graph.

Put everything that can be prepared ahead of time in the install command: dependency installs, code generation, compiled artifacts and warm disk caches. Install runs during every Build and may run on top of disk state from an earlier one, so Cursor asks for a command that is complete and idempotent. Use the start command, and terminals for app processes, for anything that must be running during the session.

The dividing line is what survives a snapshot. Builds keep disk state only, so running processes, shell exports and in-memory caches are gone when an agent boots. Docker sits on both sides of that line. Images and stopped containers persist, because Docker's data directory is on disk, but the Docker daemon has to start again in the start command.

Leaving everything in start keeps the old wait on every run and gives up much of what Builds offer. The right configuration starts quickly and still runs the current code with the services it needs.

Split the setup by lifetime, then start a new agent and test it against the real application.

A failed Build never becomes active. Cursor notifies you, and new agents keep starting from the last successful Build while you investigate. A broken dependency update, install command or Dockerfile therefore doesn't take down the working environment. The fallback keeps an environment available, but it doesn't fix the failed Build.

Before you debug a surprising result, check which Build and commit the agent used. An agent can start from an older Build and still run newer code. Feature branch runs check out the requested branch on top of the Build. Default branch runs pull the latest code at start when Update stale builds is on and the Build is older than the Staleness threshold.

To see what a run used, ask the agent to call the environment-info tool from the built-in Cursor Cloud MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition.. Its build field gives the Build ID and says whether the run reused the Build's checkout or fetched the latest code.

To reproduce a failure exactly, start an agent from the failed Build. The agent opens the machine in its failed state, where it can read the logs, fix the environment and run a test Build.

You don't need to. Cursor's release notes for the week of September 28, 2026 say environment builds are always on and can no longer be turned off. Every environment that isn't a draft gets automatic Builds, and Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. start from the latest one. The exception is a team that requires Self-Hosted Machines: Cursor builds no environments for that team or its members, and the Builds tab says builds are turned off.

At launch, Cursor's August 13, 2026 changelog said new environments used Builds automatically and existing ones had to opt in. The opt-in was Enable Builds in the environment's Builds tab, or Run setup agent first to test the migration and review proposed config changes. Environments that had Builds turned off now show their active Build and any recurring Build failures.

To check that an environment's Builds work, use its Builds tab.

1. 1Open the environment in Cursor's Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. dashboard.
2. 2Select the Builds tab and look at the active Build and any recent failures.
3. 3Select Trigger build if you need a Build now, and wait for a successful status.
4. 4Start a test agent and confirm that it used the expected Build and commit.

Cursor starts a Build on a schedule, when you save the configuration or change its secrets, when you select Trigger build, or when an agent runs a test Build. A scheduled check skips the Build if nothing changed.

The Staleness threshold is not one of those triggers. It decides whether an agent pulls newer default-branch code when it starts.

The Builds tab lists every Build with its trigger type, status and start time, and opening one shows its details and logs. From the tab you can trigger, activate, deactivate or cancel a Build, and start an agent from a specific one.

Look there first when one agent starts quickly and another does not, or when a dependency differs between runs. Match a failed log to its commit before you change the setup.

Agents can inspect and manage Builds with built-in tools, but a person should still review changes to the environment setup. Install commands run code, fetch dependencies and can read team and environment secrets. A proposed repair therefore crosses the same supply-chain and credential boundary as any other environment change. Review the diff, rerun the Build, and confirm a new agent used it before you call the repair done.

Builds are included with Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. at no additional cost. Model usage and the rest of your Cloud Agent usage still bill as normal. Builds remove repeated environment preparation. They don't make the agent's coding, tool calls or model tokens free.

Measure your own before and after, from agent launch to a usable first response. Track separately whether the app can run its checks. Keep the repo, commit, region and environment setup fixed between runs. Cursor's reported 10x boot and 3x time-to-first-token gains are useful launch evidence, but only your own runs show whether Builds removed the delay that mattered in your project.

Count failed Builds too, instead of averaging only successful starts. A faster warm path can sit next to a brittle install command. Track success rate, fallback frequency and time to repair beside startup latency, so you know whether agents are available more often or only start faster on a good day.