# \*\*Title:\*\* Cloud Agents API: allow \`repos\[\].startingRef\` with a named cloud environment (or a per-environment clone branch)

**URL:** <https://forum.cursor.com/t/title-cloud-agents-api-allow-repos-startingref-with-a-named-cloud-environment-or-a-per-environment-clone-branch/170830>\
**Category:** Feature Requests\
**Tags:** github, cursor-sdk, cloud-agents\
**Created:** [September 6, 2026, 9:19pm UTC](https://forum.cursor.com/t/title-cloud-agents-api-allow-repos-startingref-with-a-named-cloud-environment-or-a-per-environment-clone-branch/170830 "2026-09-06T21:19:02Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![bububin](https://avatars.discourse-cdn.com/v4/letter/b/41988e/32.png) [@bububin](https://forum.cursor.com/u/bububin)\
**Post date:** [September 6, 2026, 9:19pm UTC](https://forum.cursor.com/t/title-cloud-agents-api-allow-repos-startingref-with-a-named-cloud-environment-or-a-per-environment-clone-branch/170830/1 "2026-09-06T21:19:02Z")

</div>

### Feature request for product/service

Cloud Agent (GitHub, Slack, Linear,…)

### Describe the request

Cloud agents as programmable infrastructure is the most exciting thing Cursor ships right now, and I’ve gone all in on it. I’m not using them as a coding assistant — I use them as a runtime component of a product. My backend starts an agent through the API, the agent does a long analysis job on a VM, and it calls my API back when it’s done. That works, it’s in staging, and it’s genuinely a new kind of building block. Everything below is a request from someone who wants to push this further, not a complaint.

## What I’m building

A backend service that starts cloud agents through `POST /v1/agents`. Every run needs three things: the repository cloned (the agent reads procedures committed in it), runtime secrets (object-storage credentials, a callback token), and one MCP server. All three live on a named cloud environment, so each create looks like this:

```json
{
  "agentId": "bc-...",
  "prompt": { "text": "..." },
  "model": { "id": "..." },
  "env": { "type": "cloud", "name": "my-env" },
  "autoCreatePR": false
}

```

## What I can’t do

Pick a branch. `env` and `repos` are mutually exclusive for a named Cursor-hosted environment, so adding `repos: [{ "url": "...", "startingRef": "staging" }]` to the body above returns `400 validation_error` (observed 2026-09-05). The docs state the exclusivity, so this is intended.  
The environment then clones the repository’s default branch — per the Builds docs, a Build “clones every repository in the environment at its default branch”.  
Net effect: the branch my agents run is GitHub’s default branch, and nothing in the API or in the environment settings changes that per environment.

## Why that hurts

**Staging can’t be rehearsed independently.** For a cloud agent to see a change, that change has to sit on the default branch. So I fast-forward `main` to my `staging` branch every time I want a test run, which turns the default branch into a deploy channel instead of the release branch.  
**Two environments on one repo can’t differ.** I want `my-env-staging` (secrets → staging bucket) to clone `staging`, and `my-env-prod` (secrets → prod bucket) to clone `main`. Environments already give me separate secrets and separate MCP config, but both clone the same default branch — so the moment I point the default branch at `staging`, the prod environment starts running staging code.  
Dashboard → Cloud Agents → Default settings → **Base branch** doesn’t solve this: it’s team-wide, and it only sets what agents fork from when opening pull requests. My runs use `autoCreatePR: false`, and that field doesn’t change what a named environment clones.

## What I’d like — either option works

**A. Accept `repos[].startingRef` alongside `env: { "type": "cloud", "name": "..." }`.** The environment keeps supplying image, secrets and MCP; `repos` supplies only the ref. This is already the shape people use for `env.type: "pool"` and `env.type: "machine"`, where passing both is normal.  
**B. A clone/base branch field on the environment itself** , so two environments on the same repository can track different branches.  
A is more useful to me, because it’s per-run rather than per-environment.

## The machinery looks like it already exists

The Builds docs describe environment runs on non-default branches: “Feature branch runs start from the active Build’s prepared disk, then Cursor checks out the requested branch.” I have no way to _request_ that branch from the API when I target a named environment.  
So from the outside this reads like an API-surface gap rather than a platform limitation.

## Environment

- `POST /v1/agents` (v1), called from a server-side service, not the SDK
- Named cloud environment, GitHub repository
- Observed 2026-09-05

### Operating System (if it applies)

MacOS

---

<div class="post-metadata">

**Author:** ![Colin](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/colin/32/90452_2.png) [@Colin](https://forum.cursor.com/u/Colin)\
**Post date:** [September 13, 2026, 10:33am UTC](https://forum.cursor.com/t/title-cloud-agents-api-allow-repos-startingref-with-a-named-cloud-environment-or-a-per-environment-clone-branch/170830/7 "2026-09-13T10:33:04Z")

</div>

Hey @bububin, thanks for the suggestion!

You’re right that `env.name` and `repos` can’t be combined today, so a named environment always starts from the repo’s default branch.

There are a couple of ways to get a per-run branch:

You can just ask the agent to switch branches. Your first message to the cloud agent can simply instruct it to pull and check out the branch you want, e.g., `git fetch origin && git checkout staging`. This keeps your saved environment (secrets, MCP servers, setup commands) intact and is by far the simplest workaround.

You can also drop `env.name` and just pass `repos` instead.

1. Specify the branch directly on the repo:

```json
repos: [{ "url": "...", "startingRef": "staging" }]

```

2. Include your secrets in `envVars` and your MCP server in `mcpServers` on the same request.
3. Add a `.cursor/environment.json` on that branch to supply the install/start commands.

The tradeoff with Option 2 is that it moves those settings out of the saved environment and into the API call, so it isn’t a perfect substitute, but it does let two callers run different branches of the same repo.
