Cloud agents
The cursor-cloud-agents extension adds repository delegation to an
existing BDK conversation. Cloud agents work on repository checkouts
and push branches and pull requests; your agent can hand off a task,
keep talking while it runs, inspect the result, and steer or stop the
same branch.
Mount it
// bot/extensions/cloud.tsimport cursorCloudAgents from "@cursor/bdk/extensions/cursor-cloud-agents";export default cursorCloudAgents({ cloud: { repos: [{ url: "https://github.com/acme/api", startingRef: "main" }], autoCreatePR: true, },});Launches run under the host's signed-in account (bdk login,
CURSOR_API_KEY, or CURSOR_SERVICE_ACCOUNT_KEY) and spend its
cloud-agent budget. Name the repositories the agent may target in
cloud.repos.
What the agent can do
With the extension mounted, the agent can hand off coding work and stay in the conversation while it happens:
- Hand off a task. Launch a cloud agent on one of your repositories, or on a pull request, with a self-contained brief. It gets back an agent id and a URL to share.
- Check on it. See whether the agent is still running, what it produced, and which branches or pull requests it pushed.
- Read what was done. Pull the agent's full conversation into the workspace, quote its final report, or trace the exact edits before summarizing for a person.
- Steer or stop. Send a follow-up to an agent it launched; it queues behind the current run, or interrupts it on request. Cancel a run that went sideways.
- Keep track. List the agents launched in this conversation, or everything it has launched before.
A skill teaches the model when to delegate, how to write a brief a cloud
agent can act on alone, and how to follow up. Everything the extension
launches stays bound to whoever launched it: an agent started by another
user, or outside the extension, is out of reach. That separation is only
as fine as your host's auth; a shared bearer token or --allow-anonymous
makes every caller one principal, so use
authored auth when callers need
their own.
Configure it
| Option | What it controls |
|---|---|
cloud | Launch defaults for repositories, environment, and pull request behavior. |
cloud.repos | The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can't name one, so secrets in cloud.envVars never reach a repository you didn't list. |
model | The model launched agents run. Omit it to use the account default. |
apiKey | A Cursor API key to launch with instead of the host's own. |
Adjust it
To take a capability away, such as sending follow-ups, mount as a directory and disable that tool; see overlays.
What's next
Continue with these pages:
- Extensions: how mounts, namespaces, and overrides work