Mastering Cursor Cloud Agents: A Complete Usage Guide

What are Cursor Cloud Agents

Cloud Agents are AI‑powered programming assistants that run on Cursor’s servers. They operate on a GitHub repository, can run multiple agents concurrently, and can be triggered from the editor, web UI, Slack, Linear or GitHub.

Launching Cloud Agents

From the editor

Open the Composer with Cmd+Shift+L (macOS) or Ctrl+Shift+L (Windows/Linux), select Agent mode and choose the cloud option.

From the web UI

Navigate to https://cursor.com/agents (or https://cursor.com/cn/agents) to create, view and manage agents without keeping the local machine online.

Third‑party integrations

Slack : start a bug‑fix or documentation task directly from a conversation.

Linear : link an issue to an agent for automated fixes.

GitHub : associate a repository or pull‑request so the agent can clone, modify and push changes.

Typical scenarios

Scenario 1 – Fix a bug without interrupting current work

From Slack or the editor, launch a cloud agent and describe the problem, e.g. “Login page crashes on Safari, need compatibility”.

The agent works on the bug while you continue other tasks.

When convenient, open https://cursor.com/agents or the editor to review the diff and accept or reject the changes.

Tip : For difficult bugs, run multiple agents with different models, compare the results and merge the best solution.

Scenario 2 – Batch small to‑do items

In the morning, create several agents for tasks such as adding unit tests, updating README or fixing typos.

Start them while commuting; by the time you reach the office many tasks are already completed and can be reviewed immediately.

Scenario 3 – Complex feature implementation

Plan the feature locally using Cursor’s Plan mode or a normal chat, writing out steps, interfaces and file changes.

Submit the plan as a single task to a cloud agent.

Continue other work while the agent implements the feature in the background.

Review the diff or pull‑request in the editor or on the web UI and merge or adjust as needed.

Connecting a GitHub repository (resolving “Please select a repository”)

Open https://cursor.com/dashboard?tab=integrations.

In the GitHub section click Connect .

Choose the authorization scope: All repositories for testing or Selected repositories for a specific project.

After granting read/write permissions, the repository appears in the dropdown on the agents page.

If the dropdown remains empty, refresh the page, clear the browser cache, reconnect GitHub, or verify that the repository exists on GitHub and has been pushed from the local project.

Common troubleshooting

Code storage required : Cloud Agents need a cloud‑accessible code store (a GitHub repository). Ensure the repository is linked and the Cursor GitHub App has read/write access.

Legacy Privacy Mode : This mode blocks repository access. Disable it in the Cloud Agents settings.

Email mismatch : The Cursor and GitHub accounts do not need matching emails; only the GitHub account must be authorized.

Quick‑start checklist (3 steps)

Log in to a Cursor account.

Open the Composer ( Cmd+Shift+L / Ctrl+Shift+L) and select Agent mode with the cloud option.

Write a clear natural‑language task description (e.g., “fix typo in README”, “add unit test for X”) and submit. The task appears on https://cursor.com/agents for monitoring.

Cloud Agents API (for developers)

The API enables programmatic creation, querying and management of agents, useful for CI/CD pipelines, custom dashboards or bulk operations.

Authentication

Generate an API key in Cursor → Settings. Use HTTP Basic Authentication with the key as the username and an empty password (keep the trailing colon).

curl -u YOUR_API_KEY: https://api.cursor.com/v0/agents

Typical workflow

Obtain the API key and verify repository visibility with GET /v0/me and GET /v0/repositories.

Start an agent via POST /v0/agents. The JSON body must contain: prompt.text – the natural‑language task description.

A source object, either source.repository (GitHub URL) plus optional source.ref, or source.prUrl (pull‑request URL).

Optional fields include: target.autoCreatePr – whether to create a PR automatically. target.branchName – custom branch name. model – e.g., claude-4-sonnet-thinking; omitted means Cursor selects automatically. webhook – URL (and optional secret) for asynchronous status notifications.

Poll GET /v0/agents/:id for status or retrieve the full conversation with GET /v0/agents/:id/conversation. If no webhook is configured, poll until status becomes FINISHED or FAILED.

Optional follow‑up actions: POST /v0/agents/:id/followup, POST /v0/agents/:id/stop, DELETE /v0/agents/:id.

Rate limits and best practices

GET /v0/repositories

is limited to roughly one request per minute per user; cache the result.

Prefer webhooks over frequent polling for completion notifications.

Write specific prompts in prompt.text to reduce follow‑up cycles.

Handle 4xx/5xx responses according to the API overview and implement exponential back‑off for rate‑limit errors.

Recommendations

Describe tasks concretely (what to change and the desired outcome).

For complex features, finalize the plan locally before handing it to a cloud agent.

Run multiple agents with different models for hard problems and compare results.

Observe API rate limits, especially when listing repositories.

Cloud Agents require a GitHub repository with read/write permissions and do not support MCP‑based tools.

Conclusion

Cloud Agents shift “waiting for AI” to “letting AI work in the background”, making them ideal for well‑defined, parallelizable tasks such as bug fixes, test additions or code generation from a clear plan. They need explicit instructions, GitHub access, and cannot run MCP‑based tools. The optimal workflow is to design the solution locally, then let the cloud agent execute it, freeing attention for higher‑level work.