Multi-Repo Cloud Agent Environments in Cursor: Setup

It can, and this is documented rather than folklore: Cursor's setup docs have a dedicated multi-repo environments section. You select multiple repositories when creating the environment, Cursor clones each one into the agent's machine, and that environment is reused for future agent runs and automations that use the same repo group. The docs' own examples are the common splits: frontend, backend, infrastructure and shared libraries living in separate repos.

With the full workspace cloned, the agent can inspect everything, make coordinated changes, run tests across repos and open pull requests in the repos it changes. Those four are the documented capabilities. A contract change touching an API server and its client SDK can land as reviewable PRs in both places, from one prompt.

Counting the review changes the picture a little. One prompt can produce three pull requests in three repos, which means three reviewers and a merge order that nothing is sequencing for you. Cursor documents opening the PRs and stops there. A backend change can land an hour before the client change that depends on it, and for that hour main holds a contract only one side implements.

The flow is the standard environment setup with one decision made early: pick all the repos at creation time. The steps below are in the order Cursor documents them.

1. 1Open 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](https://cursor.com/dashboard/cloud-agents) and create a new environment from the Environments view.
2. 2Connect your provider (GitHub, GitLab, Azure DevOps or Bitbucket) and select every repository the agent needs. This selection defines the repo group.
3. 3Provide the environment variables and secrets required to install dependencies and run the code across all of the repos.
4. 4Let setup complete, then verify Builds. New environments use Builds automatically. Confirm the first Build clones every repo, completes install and becomes active before relying on it.
5. 5Scope the credentials. Add secrets that belong to this repo group as environment-scoped secrets, so staging credentials for this stack never leak into other environments.

Step two is the one to slow down on, because the selection you make there is the group. Rebuilding it means walking this list again, and the part that stings is the secrets: environment-scoped ones belong to the one environment by definition, so a replacement starts with none of them. User and team secrets carry over, which is a decent argument for keeping only the genuinely stack-specific credentials environment-scoped.

The secrets in step three span two phases. Builds can access team and environment secrets while preparing dependencies. User secrets arrive only when an agent starts. Changing environment secrets triggers another Build, so confirm it succeeds before treating the new value as active.

Cursor resolves configuration by repository or repo group and the first match wins, so a repo's own .cursor/environment.json outranks both the personal and the team saved environment. For multi-repo work, the saved environment created in the dashboard is the documented home of the config. Cursor does not document a multi-root environment.json format that declares several repos from one file, so don't go looking for a repos array; it isn't in the schema.

What the schema does offer is repositoryDependencies, and it solves a narrower problem: access. It lists repos, as github.com/org/repo, that must be included in the GitHub access token generated for the environment. If a build pulls a private dependency from another repository during install, this is what puts it inside the token's reach.

{
  "snapshot": "snapshot-20260212-00000000-0000-0000-0000-000000000000",
  "install": "pnpm install",
  "repositoryDependencies": [
    "github.com/acme/shared-protos",
    "github.com/acme/design-tokens"
  ]
}

Keep the two mechanisms straight. Selecting repos at environment creation clones them into the workspace for the agent to edit. repositoryDependencies widens the access token so builds can fetch a dependency; the schema describes nothing about cloning or editing those repos.

The split has a consequence for how config changes get reviewed. A single-repo config change can arrive as a diff someone reviews, while a repo group's config changes in the dashboard, so the review trail is the environment's version history rather than a pull request. Worth deciding who can edit the environment before the group grows.

The docs name the primitives: full-workspace inspection, coordinated changes, cross-repo tests, and PRs in each changed repo. The patterns below are the task shapes those primitives support, and all of them are hard to run with single-repo agents because neither half of the change can see the other.

If you are picking one to try first, the shared library bump is the friendlier start. The consumer repos tend to have tests already, so the agent has something to check itself against, whereas an API contract change spreads the review across two teams. The usual advice about keeping an agent's workspace narrow does not really apply here, since the workspace is large on purpose. Keep the prompt to one change instead.

Some of these are documented constraints, one is a bug from the recent past, and a couple are places where the docs simply stop. The honest boundary matters here, so each item says which kind it is.

• Plan the repo group up front (docs). The documented flow selects repositories when the environment is created; the docs don't describe adding a repo to an existing environment, so design the group before you build it.
• Secrets should be environment-scoped (docs). Cursor recommends environment-scoped secrets for multi-repo environments; they apply to every repo in the environment and to no other environment.
• Automations briefly lost secrets in multi-repo environments (forum, June 2026). Automation-launched agents received none of the environment's secrets while manual and API launches got all of them. Cursor staff acknowledged the bug and the thread reports it resolved by mid-July; if you see it, launch via the API or the UI and check the secrets fix ladder.
• One VM profile carries the whole workspace (docs). Cloud agents run on a default VM profile with limited memory and CPU, and several large repos share it. Enterprise teams can contact support to raise limits; self-serve resource configuration is listed as coming soon.
• One Build prepares every repository (docs). It records one commit per repo. If that Build fails, agents continue on the last successful active Build while you inspect the failure.
• No documented repo-count limit (docs gap). Cursor publishes no maximum number of repositories per environment. Treat the practical ceiling as whatever the VM profile handles, not a stated number.

Environment-scoped is a coarser boundary than it sounds. It scopes a credential to the whole group rather than to one repo, so a production token added for the deploy repo also sits in the environment where the agent only needed to read a shared schema. On a four-repo stack owned by one team, that is probably fine and nobody thinks about it again. Across team boundaries, a second environment costs more setup and keeps the credential where it belongs.

The VM profile and the unpublished repo count interact. Adding a repo costs nothing when you create the environment and costs a little on every run afterwards, because that one default profile holds the whole cloned workspace.

With no published ceiling, I would size the group around the repos a task actually has to read and leave the rest for another environment.