Set Up Cursor Cloud Agents: Environment, Repo, First Run

A cloud agent environment is the machine the agent works on: cloned repos, installed dependencies, secrets, startup commands and network access. Cursor compares it to the setup on your laptop. An agent that can write code but can't run tests, query services or reach APIs can't close the loop on its work. Cursor calls environment setup the most important step for making cloud agents effective.

The clip below follows one run from prompt to pull request.

What happens without environment setup?

An unconfigured agent still produces work. It reads the repo and hands you a plausible diff that nobody has run. Verifying it falls to whoever opens the pull request: they check out the branch and run the suite by hand, which is the work the agent was supposed to save.

Cursor documents two main ways to configure an environment, plus a private-beta option for Enterprise teams. Both main ways let you specify an install script, which Cursor runs while it creates a Build, so dependencies are ready before an agent starts.

Agent-driven setup is the fastest path and the one Cursor recommends. A Dockerfile takes longer to write, but it is text you can diff line by line, and editing one rebuilds only the changed layers. The private-beta option splits the difference: Cursor writes the Dockerfile and you keep its version history.

Team size decides this more reliably than repo complexity. When thirty people depend on one environment, a change to the machine should arrive as a diff that someone reviews. So on a large team, we'd write the Dockerfile even where agent-driven setup would work, and accept the slower setup.

Start guided setup from the 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. You connect a GitHub, GitLab, Azure DevOps or Bitbucket account, select one or more repositories, and provide the environment variables and secrets needed to install dependencies and run the code. You can watch the agent's progress in a shared terminal. Cursor saves the environment once it verifies the code and completes a successful Build, and future agents start from the active Build. Commit the configuration to .cursor/environment.json so the whole team benefits.

Builds move repository cloning and dependency setup out of the agent's startup path. Cursor prepares a bootable environment in the background, records the environment version and the exact commit of each repository, and keeps the latest successful Build active for future agents, automations and code reviews.

Environment builds can no longer be turned off. Cursor's release notes for the week of September 28, 2026 say every environment that isn't a draft now gets automatic Builds. Teams that require Self-Hosted Machines are the exception: Builds run on Cursor-hosted machines, so Cursor doesn't build those teams' environments or their members' personal environments.

A failed Build never replaces the working one. Agents keep starting from the last successful Build while you inspect logs, commit SHAs and the Build each run used. Fix the failure anyway, before the active Build drifts too far from the repository state you expect.

1. 1Save the environment. Saving its configuration or changing its secrets starts a new Build.
2. 2Confirm the Build succeeds and becomes active. Until an environment has a successful Build, agents start on Cursor's default image without the environment's setup.
3. 3Start an agent and confirm which Build it used: ask it to call the 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. environment-info tool, whose build field has the Build ID. Then check that Build's logs and commits in the Builds tab.
4. 4If a Build fails, open it to inspect its logs, or start an agent from the failed Build to reproduce the problem.

The Cloud Agent BuildsPrepared Cloud Agent environments built in the background, with the last successful build kept active when a newer build fails. Press Enter for the full definition. guide covers activation, failed-Build debugging, staleness settings and Build provenance in detail.

Cursor runs the install script, install in environment.json, while it prepares a Build. The dashboard and docs used to call it the update script. start and any configured terminals run only when an agent starts, and each phase has its own job.

A successful Build captures disk state after install completes and becomes active. Later agents start from that prepared disk, so they don't clone the repository or install the same dependencies again. The environment.json reference covers the exact command fields and the idempotency contract.

Put durable preparation in install and live processes in start. A database server started during a Build is gone after Cursor snapshots the machine, while installed packages and generated files remain. Commands for services an agent needs only on some tasks belong in AGENTS.md, so the agent can run them when the work calls for them. Write that section for someone who has never seen the repo.

Cursor recommends the Secrets tab on cursor.com, which exposes each value to the agent as an environment variable. Cloud agents often need secrets such as API keys and database credentials to run and test code like a developer. Cursor's docs add guidance for three situations.

Cursor also documents a shortcut that it stops short of recommending. Any .env.local files present when you take a snapshot can be saved into it, so later agents find the values without a Secrets entry. Rotating a key then means taking a new snapshot instead of editing a field. The docs still call the Secrets tab the recommended approach for security and management.

Saving environment configuration or changing its secrets triggers a new Build. Team and environment secrets can be used during Builds. User secrets are added only when an agent starts, so they never enter the shared snapshot. If a credential is missing, check whether the new Build succeeded and whether the secret belongs to the Build or the run. The secrets troubleshooting page covers the full ladder.

For AWS, Cursor can assume an IAM role you provide, so you grant permissions without sharing long-lived credentials.

1. 1Create the IAM role in your AWS account and note its ARN.
2. 2Add a user or team secret named CURSOR_AWS_ASSUME_IAM_ROLE_ARN set to that ARN.
3. 3Have a team admin generate an external ID in the Advanced section of team settings.
4. 4Update the role's trust policy to trust Cursor's role assumer, with your team's external ID as the condition.

Cursor then sets AWS_CONFIG_FILE, AWS_PROFILE=cursor-cloud-agent and AWS_SDK_LOAD_CONFIG=1, so the AWS CLI and SDKs pick up the profile automatically.

Yes, with some VM-specific configuration. Cloud agents support Docker workflows and can reach private services through Tailscale or Cloudflare Tunnel. Each card gives the pattern Cursor documents.

Two of the cards come down to userspace networking. Tailscale needs it because its default mode doesn't work in these VMs, and cloudflared works as shipped because it already runs in userspace. Docker is the awkward one, because it runs inside another container layer. If a private service is unreachable, check the egress allowlist first: on a restricted-egress environment, a missing hostname looks much like a tunnel that never came up.

The Cloudflare card covers HTTP services. For private databases, the docs use a Cloudflare TCP Access app with cloudflared access tcp in your startup command, and point your test command at the local listener it opens. That command belongs in start, not install, because it has to keep running while the agent works.