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 specify an update command that runs before the agent starts so dependencies stay current (for example npm install or pip install). The table below maps each 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.

When a new machine boots, Cursor starts from the base environment, runs the update command (called install in environment.json), then runs the start command and any configured terminals. Each phase takes different commands, listed below.

• `update` / `install`: dependency setup such as npm install or bazel build. It must be idempotent because it can run more than once and on partially cached state.
• `start`: processes that should stay alive while the agent runs. You can skip it in many repos; if your environment depends on Docker, add sudo service docker start here.
• `terminals`: app code processes that run in a tmux session shared by you and the agent.

After update completes, if it took more than a few seconds, Cursor takes an internal checkpoint snapshot and tries to start future agents from it, which is why commands like pnpm install lead to fast startup. Caching is best effort, so infrequently used repositories may see slower startup. The environment.json reference covers the idempotency contract that comes with running on cached state.

The instinct is to put everything the agent might need into update so it's always there. That's the wrong way round. update runs on the boot path of every agent you launch, so an image build there costs startup time on every run, including the ones that only touch a README, and Cursor names exactly those commands (building images, starting services) as what slows startup. Keep update to cached dependency work, then let AGENTS.md carry the per-task commands the agent should run for itself.

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.

A secret added after the environment was built does not reach machines already built from it, so update or recreate the environment before you start debugging the app. The secrets troubleshooting page works through that cause and four others.

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.