# Cloud agents

The `cursor-cloud-agents` extension adds repository delegation to an
existing Agent SDK 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

```ts
// bot/extensions/cloud.ts
import cursorCloudAgents from "@grok/agent-sdk/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 (`agent-sdk 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](/docs/reference/channels.md#auth-policies) 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. |
| `cloud.teamMcpServers` | The team MCP servers, by name, that launched agents may use (up to 50 names, matched case-insensitively; every team server with a listed name is kept). Every other team server is left out. Personal servers and `cloud.mcpServers` aren't filtered. Omit it to give agents every team server the launching account can use. |
| `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](/docs/reference/extensions.md#adjust-a-mounted-extension).

## What's next

Continue with these pages:

- [Extensions](/docs/reference/extensions.md): how mounts, namespaces, and
overrides work