Cloud Agents
Multi-Repo Cloud Agent Environments in Cursor: Setup
Yes, one Cursor cloud agent environment can span several repositories. Select multiple repos when you create the environment; Cursor clones each into the agent machine, reuses the setup for runs and automations on the same repo group, and the agent can make coordinated changes and open pull requests in every repo it touches.
On this page
Can one cloud agent work across multiple repositories?
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.
The capability claim is specific. 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. That last clause is the point of the feature: a contract change that touches an API server and its client SDK lands as reviewable PRs in both places, from one prompt.
- Workspace
- Single-repo environment
- One cloned repo
- Multi-repo environment
- Every selected repo, cloned side by side
- Config resolution
- Single-repo environment
- By repository
- Multi-repo environment
- By repo group
- Reuse
- Single-repo environment
- Runs against that repo
- Multi-repo environment
- Runs and automations using the same repo group
- Pull requests
- Single-repo environment
- One repo
- Multi-repo environment
- Opened in each repo the agent changed
- Secrets fit
- Single-repo environment
- User or team secrets usually suffice
- Multi-repo environment
- Environment-scoped secrets, which apply to every repo in the environment
| Single-repo environment | Multi-repo environment | |
|---|---|---|
| Workspace | One cloned repo | Every selected repo, cloned side by side |
| Config resolution | By repository | By repo group |
| Reuse | Runs against that repo | Runs and automations using the same repo group |
| Pull requests | One repo | Opened in each repo the agent changed |
| Secrets fit | User or team secrets usually suffice | Environment-scoped secrets, which apply to every repo in the environment |
What actually changes when an environment spans repos, per cursor.com/docs/cloud-agent/setup.
This is covered hands-on in Agent Mode Foundations — 6 short modules, free to read.
How do I set up a multi-repo environment?
The flow is the standard environment setup with one decision made early: pick all the repos at creation time. The documented path selects repositories when the environment is created, so treat the repo group as something you design, not something you grow into.
- 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.
- 2Connect your provider (GitHub, GitLab, Azure DevOps or Bitbucket) and select every repository the agent needs. This selection defines the repo group.
- 3Provide the environment variables and secrets required to install dependencies and run the code across all of the repos.
- 4Let agent-driven setup run. Cursor's agent installs dependencies while you watch in a shared terminal, then you save a snapshot of the machine so future runs start fast.
- 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.
The environment is reused by automations on the same repo group. A scheduled or triggered automation that needs the whole stack, say nightly dependency bumps across four service repos, inherits the same cloned workspace and setup instead of rebuilding it per repo.
How does environment.json work across repos?
Configuration resolution happens by repository or repo group, first match wins: a .cursor/environment.json in the repo, then a personal saved environment, then a 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 your build fetches a private sibling repo during install, this is how the token learns it's allowed to.
{
"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.
What cross-repo tasks work well?
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 each one is miserable to do with single-repo agents because the halves can't see each other.
Change an endpoint in the backend repo and update the client SDK or frontend calls in the same run. The agent reads both sides of the contract, so the types actually line up, and each repo gets its own PR.
Update the library repo, then fix the fallout in every consumer repo in the same workspace. Cross-repo tests catch breakage before the PRs open rather than after the merge.
A new environment variable, queue or bucket usually means an infrastructure repo edit and an application repo edit. One agent holding both avoids the half-shipped state where config exists and code doesn't.
Recurring work like dependency upgrades or lint policy rollouts runs as an automation against the repo group, reusing the environment instead of setting up N machines for N repos.
What are the limits and gotchas?
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.
- Caching is best effort (docs). Checkpoint snapshots make active repo groups start fast, but infrequently used environments start slower.
- 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.
The environment's configuration page on the dashboard shows which environment is active and all past active versions. When a multi-repo run behaves oddly, confirm which version actually served it before debugging the config you think is live. Version history and restore live in the settings view.
Frequently asked questions
Can a cloud agent open pull requests in more than one repo from a single task?
Yes. In a multi-repo environment the agent makes coordinated changes across the cloned repos and opens pull requests in the repos it changes, so one task can produce a PR per affected repository.
Do my secrets apply to every repo in a multi-repo environment?
Environment-scoped secrets do: they apply to every repo in that environment and are not available to other environments. Cursor recommends them for multi-repo setups, staging credentials and repo groups with different access needs.
Do automations use the same multi-repo environment?
Yes. Cursor reuses the environment for future agent runs and automations that use the same repo group, so scheduled work against the stack inherits the cloned workspace and setup.
Is there a limit on how many repositories one environment can include?
Cursor doesn't publish one. The docs say to select multiple repositories at creation without stating a maximum. The practical constraint is the default VM profile's memory and CPU, which Enterprise teams can ask support to raise.
Sources & last verified
- Cursor Docs - Cloud Agent Setup: multi-repo environments
- Cursor - environment.json schema
- Cursor Docs - Cloud Agent Automations
- Cursor Forum - Automation-launched agents get no secrets (multi-repo)
Cursor ships frequently. Facts verified against primary sources on July 16, 2026.