Cursor Cloud Agents: Setup

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.

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.

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. The list below maps each phase to what belongs in it.

• `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. A practical pattern is to run basic cached dependency updates in update, then add instructions to AGENTS.md so the agent figures out the per-task commands it needs.

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.

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.