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:
{
"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