Cursor Cloud Agent Builds for QA can make agent sessions start from a prepared environment instead of cloning repositories and installing dependencies on every run. Faster startup is useful, but the deeper quality question is whether the environment is reproducible, fresh, correctly scoped and traceable to the agent result.

This tutorial creates a disposable cloud environment and validates the Build lifecycle: trigger, prepare, snapshot, activate and start. You will prove which commits and configuration an agent used, test idempotent installation, separate disk state from runtime state, exercise stale-source rules, verify feature-branch dependency refresh, inject a failed Build, check secret boundaries and reproduce problems from an exact Build.

What Cursor Builds do

The current Cursor Cloud Agent Builds documentation describes a Build as a bootable snapshot prepared ahead of agent runs. Cursor starts from the base image, clones every repository at its default branch, runs the environment’s install command to completion, records the environment version and exact commit SHA for each repository, then activates the Build only after success.

New agents, automations and code reviews start from the active Build. A failed Build does not replace the last successful one. The dashboard records which Build each agent used, and teams can inspect logs, trigger a Build, activate or deactivate one, cancel an in-progress Build, start an agent from a specific Build, and configure stale-source behavior.

Cursor’s official Builds announcement says prepared environments improve startup performance. Treat those performance numbers as Cursor’s product measurements, not a guarantee for your repository. QA should measure its own median and tail startup time.

Define the environment contract

Every cloud-agent result must identify the Build, environment version and repository commits it started from. A Build may become active only after the complete install contract succeeds. Failed or stale Builds must be visible, reproducible and unable to silently replace the reviewed environment.

Record a trial ID, Build ID, trigger type, environment version, base-image identifier, repository SHAs, configuration hash, install-script hash, status, activation time, freshness threshold, stale-update setting, build secrets used, agent-run ID, checked-out branch, post-start SHA, dependency-lock hash, startup duration and deterministic test result.

Step 1: create a safe fixture

Use a private disposable repository with no customer data. Include:

  • a tiny application and deterministic smoke test
  • a lockfile and dependency-version reporter
  • a generated file whose content records the fixture version
  • an install counter stored in a harmless workspace file
  • a startup service that exposes a synthetic health endpoint
  • a test-only team or environment secret canary
  • a test-only user-secret canary

Never print actual secret values. The tests should assert presence or absence using one-way markers or fixed expected booleans.

Step 2: separate install from start

Cursor’s Cloud Environment Setup guide says the install script runs during every Build and must be idempotent because it may run on previously prepared disk state. Use it for repeatable preparation such as dependency installation, code generation, artifact compilation and warming disk caches.

Long-running processes belong in start or configured terminals. Builds preserve disk state, not processes, exported shell variables or in-memory caches. Put the synthetic server in start, not install.

Run the same Build configuration twice. The second run must finish without duplicate generated entries, corrupted caches, repeated migrations or different lock resolution. Compare file hashes and deterministic tests after both trials.

Step 3: test before broad activation

For an existing environment, open the Builds tab and use a setup agent or a test Build before enabling the workflow broadly. Review every proposed configuration change. The setup agent can propose dashboard configuration or open a pull request when the environment is defined in .cursor/environment.json, but it does not replace human approval.

Verify that the first successful Build contains the expected repository commit, installed dependency versions, generated artifact and configuration hash. Start one agent from that specific Build and run the smoke test. Capture the Build-to-agent association shown in the dashboard.

Step 4: verify the lifecycle and triggers

Official docs list recurring, configuration-change, manual and agent-requested Build triggers. Exercise each one in isolation:

Trigger Controlled change Expected evidence
Recurring New default-branch commit Scheduled Build with captured new SHA
Configuration Change install-script marker New environment version and Build
Manual Select Trigger build Manual type and reviewer identity
Agent-requested Run a test setup flow Draft/test Build linked to the agent

Do not assume a trigger succeeded because the Build exists. Confirm prepare completed, snapshot was saved and the intended Build became active.

Step 5: test failed-Build fallback

Create a new commit that makes the install command exit unsuccessfully after writing a distinctive synthetic error. Trigger a Build. It should be marked failed and must not replace the active successful Build.

Start a new agent normally. Verify its recorded Build ID is still the last successful one, its repository and dependency evidence matches that Build, and its smoke test passes. The failure must remain visible in logs with the exact source commit that caused it.

This behavior preserves availability, but it introduces an important risk: agents may continue on older code. The dashboard evidence must make that fallback obvious to the tester and release owner.

Step 6: validate source freshness

For default-branch runs, Cursor starts from the commit recorded by the active Build. When Update stale builds is enabled and the Build is older than its configured threshold, the agent pulls the latest default-branch code at start. With the setting off, it uses the recorded commit as-is.

Test three cases:

  1. Fresh Build below the threshold: expect the recorded SHA.
  2. Old Build above the threshold with updating enabled: expect the latest default-branch SHA after startup.
  3. Old Build above the threshold with updating disabled: expect the recorded SHA and an explicit stale result in your QA report.

Capture both the Build’s stored SHA and the actual checked-out SHA inside the agent. Provenance requires both when a startup update is possible.

Step 7: exercise feature-branch dependency drift

A feature-branch run reuses the active Build’s prepared disk, then checks out the requested branch. Cursor documents that the source matches the selected branch while dependencies come from the Build unless the branch changes them and the agent refreshes the environment using the configured context and install command.

Create one branch with only source changes and another with a lockfile change. The source-only branch should retain compatible prepared dependencies. The lockfile branch must refresh dependency state before testing. Assert the installed dependency version, lock hash and smoke-test result rather than trusting a textual claim from the agent.

Step 8: test disk-only snapshot semantics

During install, create a file marker, export a shell variable and start a short-lived synthetic process. After an agent starts from the Build:

  • the file marker should exist because it is disk state
  • the exported variable should not survive unless configured again at runtime
  • the process should not be running
  • the configured start service should launch freshly and pass its health check

This catches a common environment bug: a Build appears successful because setup worked during preparation, but the agent cannot reproduce the required runtime state.

Step 9: verify secret boundaries

Cursor’s docs say Builds can access team and environment secrets needed for installation, while user secrets are added only when an agent starts and do not become part of the shared snapshot.

Configure a harmless build-secret canary and user-secret canary. During the Build, assert only the build canary is available. During the agent run, assert the runtime canary is available according to policy. Search Build logs, generated files, caches and artifacts for the literal canary values. Any value persisted into the snapshot or logs is a failure.

Rotate the test secret and verify that a configuration or secret change triggers a new Build where expected. Keep production credentials out of this exercise.

Step 10: validate multi-repo provenance

One Build can prepare multiple repositories and records one commit for each. Create a two-repository fixture: an application and a shared test library. Build from known commits, then advance only the library’s default branch.

Confirm the Build details show the original pair of SHAs. Exercise the freshness rule and record the actual pair used by the agent. Run a compatibility test that proves the application and library versions work together. A single environment-level label is insufficient evidence when repositories can move independently.

Step 11: reproduce an exact failure

The Builds tab can start an agent from a specific successful or failed Build. Use the deliberately failed Build to reproduce its environment. Inspect the captured log and machine state, propose the smallest configuration correction, and run a test Build.

Do not activate the repaired draft immediately. Compare install outputs, dependency hashes, secret exposure checks, runtime health and smoke tests with the known-good baseline. Activate only after a reviewer accepts the evidence. Retain the failed Build ID and replacement Build ID in the defect.

Step 12: measure the claimed benefit locally

Measure at least 20 comparable agent starts before and after Builds. Record time to ready environment, time to first meaningful agent output and time to passing smoke test. Report median, 90th percentile and failure rate.

Exclude runs with different repository size, network policy, dependency changes or runner resources. Performance is a repository-specific observation, not proof of correctness. A fast stale environment is still a defect.

QA rollout checklist

  • Build ID, environment version and every repository SHA are captured
  • Install is complete, deterministic and idempotent
  • Long-running services are started at runtime, not snapshotted
  • All four trigger types have traceable evidence
  • Failed Builds cannot replace the known-good active Build
  • Fallback to an older Build is visible in the QA report
  • Freshness thresholds are tested both enabled and disabled
  • Feature-branch lockfile changes refresh dependencies
  • Disk, process, environment-variable and in-memory state boundaries are proven
  • Build and user secret canaries never leak into logs or snapshots
  • Multi-repo runs record and test every commit pair
  • Failed environments can be reproduced from an exact Build
  • Draft repairs are tested before activation
  • Startup performance uses repeat trials and percentile reporting
  • Humans retain environment activation, merge and release authority

Official sources

Prepared environments remove repeated setup from the critical path, but they also introduce state that QA must identify and challenge. The defensible workflow is to prove install idempotency, capture exact provenance, test stale and failed paths, respect secret boundaries, reproduce exact Builds and require deterministic application evidence before trusting an agent result.