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 describes it as similar to the setup on your laptop. An agent that can write code but can't run tests, query services or reach APIs cannot close the loop on its work, so 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, who checks out the branch and runs the suite by hand. That is the time the agent was supposed to save, and spending it twice is, I suspect, most of why people try cloud agents once and never come back.

There are two ways to configure the environment, and both let you define the machine and its commands. With Builds enabled, the install command prepares dependencies in the background while start and terminals wait for the agent run. The table below maps each setup option to when Cursor recommends it.

The table recommends row one on speed. What it leaves out is what you own afterwards. Agent-driven setup leaves you a snapshot, a saved VM that is quick to produce and hard to read back six months later, and Cursor's environment-recovery docs list a snapshot expired after inactivity among the cases where a run comes up on the default base image with a warning instead. A Dockerfile is text you can diff, and editing one rebuilds only the changed layers. The third row splits the difference, with Cursor writing the Dockerfile and you keeping the version history.

Team size decides this more reliably than repo complexity does. Two people can rebuild a snapshot from memory when it breaks. Thirty can't, so on a large team I'd write the Dockerfile even where the agent-driven path would have worked, and accept the slower start.

For agent-driven setup, 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. After Cursor verifies the code works, you save a snapshot so future agents start faster, and commit the config 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 exact commit for each repository, and keeps the latest successful Build active for future agents, automations, and code reviews.

A failed Build never replaces the working one. Agents continue from the last successful active Build while you inspect logs, commit SHAs, and the Build used by each run in the dashboard. This is a reliability boundary, not permission to ignore a broken setup: fix it before the active Build drifts too far from the repository state you expect.

1. 1For a new environment, confirm its first automatic Build succeeds before relying on it.
2. 2For an existing environment, open the Builds tab and choose Run setup agent or Test build to review the migration.
3. 3Select Enable Builds when the tested configuration is ready for agent runs.
4. 4Open Build history after the first run and confirm the recorded Build, logs, and repository commit.

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.

With Builds enabled, the commands no longer share one startup path. Cursor runs the dashboard update command, called install in environment.json, while preparing a Build. It runs start and configured terminals only when an agent starts. Each phase has a separate job.

• `update` / `install`: runs during each Build. Put dependency installation, generated code, compilation, and disk-cache warming here. Keep it complete and idempotent because Cursor may run it repeatedly on prepared disk state.
• `start`: runs at the start of each agent session. Put Docker, databases, tunnels, and other services that must be fresh here.
• `terminals`: starts app processes for the agent run in a tmux session shared by you and the agent.

A successful Build snapshots disk state after install completes and becomes active. A later agent starts from that prepared disk, so it does not clone the repository or install the same dependencies again. The environment.json reference covers the exact command fields and idempotency contract.

Put durable preparation in install and live processes in start. A database server started during a Build will be gone after Cursor snapshots the machine, while installed packages and generated files remain. Per-task commands still belong in AGENTS.md so the agent can choose them when the work actually calls for them.

That hand-off only works if the agent finds the instruction, so write the cloud section for someone who has never seen the repo.

To run and test code like a developer, cloud agents often need environment variables and secrets such as API keys and database credentials. The recommended approach is the Secrets tab in Cursor settings on cursor.com, which exposes the values to the agent as environment variables. The list below covers the cases Cursor documents.

• Environment-scoped secrets: use these when a credential should be available only to agents that use one environment. They apply to every repo in that environment and are not shared with others.
• Sign-in credentials and 2FA: add the same login credentials you use locally as secrets. For TOTP-based 2FA, add the TOTP shared secret too; the agent generates the current 6-digit code with oathtool --totp -b "$TOTP_SECRET".
• Monorepos with multiple `.env.local` files: add values from all of them to the same Secrets tab, use unique variable names when keys overlap (such as NEXTJS_* and CONVEX_*) and reference them from each app.

Cursor documents a shortcut here and stops short of recommending it. Any .env.local files present when you take a snapshot can be saved into that snapshot, so later agents find the values without a Secrets entry at all. It works. Rotating a key then means taking a new snapshot rather than 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 and do not enter the shared snapshot. If a credential is missing, check whether the new Build succeeded and whether the secret belongs to the Build or run phase. The secrets troubleshooting page covers the full ladder.

For AWS, Cursor can assume a customer-provided IAM role so you grant permissions without sharing long-lived credentials. You create the role and note its ARN, add a secret named CURSOR_AWS_ASSUME_IAM_ROLE_ARN, have a team admin generate an external ID from team settings, and update the role's trust policy to allow Cursor's role assumer. 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. The cards below summarize the pattern Cursor documents for each.

Two of those three cards turn on the same word. Tailscale needs userspace networking because its default mode doesn't work in these VMs, and cloudflared works as shipped because it already runs there. Docker is the awkward one, and the reason the docs give is the container layer it runs inside. If a private service is unreachable, I'd still check the egress allowlist before any of that, since a missing hostname on a restricted-egress environment looks much like a tunnel that never came up.

The Cloudflare pattern in that card is for HTTP services. Private databases get their own route in the docs, a Cloudflare TCP Access app with cloudflared access tcp in your startup command, and your test command pointed at the local listener it opens. It goes in start rather than update, since it has to stay running while the agent works.