How Do You Set Up a Cloud Agent Environment in Cursor?
Open the Cloud Agents dashboard at cursor.com/dashboard/cloud-agents, or the Agents Window, and start guided setup. You connect a repo and give it the secrets it needs, then an agent installs dependencies, verifies the code and saves the environment after a successful Build. Cursor says this takes under 10 minutes.
Set up the cloud environment for this repo so future agents can test their work. Install dependencies with: [install command] Run the app with: [dev command] Run checks with: [test, type check and lint commands] Secrets needed: [names only, I'll add values in the Secrets tab] Network access needed: [domains such as your package registry and API] Verify each command works. Then write what you learned into AGENTS.md: how to run and test this project, and anything that surprised you.
- .cursor/environment.jsononly if the location points to it
- Team saved environment
- Personal saved environmentchecked first
Try it now
- 1Open the Environments section of the Cloud Agents dashboard and start guided setup, then connect your Git provider and pick a repository.
- 2Add required values in the Secrets tab, and watch progress in the shared terminal session.
- 3Start a Cloud Agent with a small task that needs your tests. It worked if its PR shows the tests actually ran.
Use it when
Before you rely on Cloud Agents for a repo, or as soon as a run says it couldn't test its work. Use a multi-repo environment when a task spans separate frontend, backend, infrastructure or shared-library repos, since Cursor clones each one onto the machine.
Skip it when
If your project can't run outside your own network, setup alone won't solve it. You'd need private connectivity or Self-Hosted Machines first. And a one-off doc edit that needs no build or tests may not justify a full setup yet.
Why it works
Cursor calls environment setup the most important step for improving Cloud Agents, because an agent that can't run tests, query services or reach APIs can't check its work. Cloud Agents run on isolated Ubuntu machines. A Build prepares repositories, tools and dependencies in the background, so future agents start from a ready machine rather than installing everything again. Think of it as onboarding a new developer: Cursor's docs describe the agent as smart but low-context.
Example
Say a Next.js app needs Postgres and a Stripe test key. You start guided setup, provide DATABASE_URL and STRIPE_TEST_KEY as secrets, and the agent installs packages, starts the database and runs the test suite. After a successful Build, the next agent begins with all of that ready. You commit .cursor/environment.json so the whole team starts from the same place.
Going further
Environment selection has a trap. Cursor uses the first match of: a personal saved environment, a team saved environment, then .cursor/environment.json in the repo. And environments you create start with environment.json location set to None (skip environment.json), so a committed file can be silently unused until you point it there. Self-Hosted Machines never read that file. If a run can't reach something, check egress controls, since required URLs must be allowed, and for cloud roles, Cursor prefers OIDC tokens to long-lived keys.
Common mistakes
- Skipping setup and judging Cloud Agents on code they never ran.
- Editing
.cursor/environment.json, and not noticing that a personal or team saved environment wins. - Leaving a personal override in place after testing, so your runs differ from the team's.
- Blaming the model when custom dev commands fail. Cursor found some models forget arguments or get distracted by noisy build logs, and recommends writing tools the agent is good at using.
Sources
- Cloud Environment Setup, Cursor Docs
- Cloud Agents, Cursor Docs
- Cloud Agents Best Practices, Cursor Docs
Checked 6 November 2026. Products change often, so confirm details with the vendor.