Cursor Cloud Agent: your first PR from the cloud (2026)

Cursor Cloud Agent (formerly Background Agent) is a coding agent that runs on an isolated Cursor machine, clones your repository from GitHub and hands work back as a branch and pull request — not only as a diff on your laptop. Use it when you want to finish a task while doing something else, or when the repo is not open in the IDE. It is not Grok Bot (teammates and Agent Computer for Gmail, PDFs and browser work), not Hermes in a local terminal, and not Grok web chat at grok.com. Official docs: https://cursor.com/docs/cloud-agent. You can start runs from desktop (Cloud mode in the agent), from https://cursor.com/agents or from an @cursor comment on GitHub if your team enabled it. This tutorial assumes a GitHub repo you can push to and a small change you can already describe.

1. Steps 1

   Cloud Agent or local Agent: decide once

   Use **local Agent** in Cursor desktop when you are in the repo, want to see each diff immediately and run tests on your machine. Use **Cloud Agent** when the job may take a while, you do not have the project open, or you want the deliverable packaged as branch + PR on GitHub. Cloud Agent clones the remote on Cursor's VM, installs per repo environment (or an environment snapshot) and pushes to a branch — often `cursor/…` — for you to review on GitHub. Do not use it for «explain the codebase» with no code change: that is Ask locally. Do not confuse it with Grok Bot: that product automates browser and documents in Agent Computer; it does not open PRs on your repo the same way.

   What you should see: A one-line decision written down: «Cloud: documented fix for issue #N» or «Local: spike on my laptop».

2. Steps 2

   Define a job that fits one PR

   Open the issue, failing test or review comment you want to address. Write three sentences: **symptom** (what fails or is missing), **scope** (which folders or files may change and which may not), **proof** (command or check that must pass). Example: «`auth.test.ts` fails on empty email; fix validation only under `src/auth/`; `npm test` green in that package». If there are no tests, define something observable: «README lists the correct build command». Avoid «improve the app» or «refactor auth». If you are new to the repo, skim cursor-repo-existente before delegating.

   What you should see: A note with symptom, explicit scope (including «do not touch») and a verification command.

3. Steps 3

   Write an outcome prompt (goal, not line-by-line patch)

   In the Cloud agent field, paste a structured brief:

   1. **Context:** link to `https://github.com/org/repo` and base branch (`main` unless you say otherwise). 2. **Goal:** what must be true when done (green tests, fixed string, doc added). 3. **Limits:** do not change CI, do not touch `affiliates.ts`, do not invent URLs. 4. **Definition of done:** «open PR against main, descriptive title, `npm run build` passes».

   Do not paste «change line 42 to X» unless it is an obvious typo. Cloud Agent picks implementation when the outcome is clear. Ask explicitly for a pull request if your workflow needs it — docs describe merge-ready PRs. Docs: https://cursor.com/docs/cloud-agent

   What you should see: A 10–20 line prompt with repo URL, success criteria and limits. No micro edit list of ten items.

4. Steps 4

   Confirm connected repo and start the run

   In **Cursor desktop**, open agent chat and pick **Cloud** in the dropdown under the input (exact label may vary; look for Cloud / Cloud Agent). On the **web**, go to https://cursor.com/agents, select the correct GitHub repository and paste the same prompt. If your org just connected GitHub, an admin must have authorized repo access — otherwise clone fails. Double-check the repo name in the UI before send. Optional: on a GitHub issue or PR, an `@cursor` comment with the same brief if your team uses that integration. Submit and note the time; long runs are normal on monorepos.

   What you should see: Run in «running» or similar state, with the correct GitHub repo shown in the agent header.

5. Steps 5

   Wait for branch, commits and PR link

   While it runs, you can close the tab: the agent keeps working on the VM. Return to the run on cursor.com/agents or desktop history. When finished, you should see a created branch (often `cursor/` prefix), listed commits and a **View PR** or similar link to GitHub. If the run fails, read the log on the agent page — common causes are denied clone, broken environment build or impossible prompt. Do not relaunch with the same text without fixing the error. If no PR appears, check whether you asked for one and whether push permission succeeded; the API documents `autoCreatePR` for integrations, but in the UI the usual success path is branch + PR.

   What you should see: «Completed» status, remote branch on GitHub and an open PR (draft or ready) with a title that matches your brief.

6. Steps 6

   Review the PR on GitHub like a teammate's

   Open the PR on GitHub. Read the agent's title and description. On **Files changed**, check scope: only allowed folders? Unexpected config, lockfiles or snapshot churn? Walk through your definition of done: if you asked for `npm test`, see whether the agent mentioned it or CI already runs on the repo. Reject suspicious patterns: emptied tests, broad `skip`, dependencies added for no reason. Use inline comments to request fixes or handle trivial follow-ups locally. Cloud Agent may attach artifacts (screenshots, logs) per docs — use them to validate UI for visual changes.

   What you should see: A bounded diff, PR body that states the goal, CI checks running or green if the repo has them.

7. Steps 7

   Merge, request changes or close

   If the diff meets the brief and CI passes (or there is no CI and you verified manually), merge with your team's strategy. If something is missing, leave concrete comments («restore the assert on line X») and relaunch Cloud Agent on the same repo citing the PR number, or fix on the bot branch yourself. If the approach is wrong, close without merge and write a tighter prompt. Note what worked in the brief for the next run. When you need many local iterations, switch back to local Agent (cursor-como-ide-con-ia). For inbox or PDF automation, use Grok Bot or Hermes — not this flow.

   What you should see: Merged PR or review comments sent; in your notes, an improved prompt version for next time.