| name | start-cursor-cloud-session |
| description | Starts a new Cursor Cloud Agent session via the Cloud Agents API and returns the session URL. Use when the user wants a Cursor cloud session, cloud agent, remote Cursor worker, AFK Cursor run, or mentions CURSOR_API_KEY and a new cloud VM. |
Start a Cursor Cloud session
Spin up a new Cursor Cloud Agent on Cursor-hosted infrastructure. Each create returns a durable agent plus an initial run and a URL like https://cursor.com/agents/....
This is for one-off or hand-off cloud work. For multi-issue Ralph loops, use the ralph skill with --worker remote-cursor instead.
Prerequisites
| Requirement | Notes |
|---|
CURSOR_API_KEY | Cursor Dashboard → Integrations |
| GitHub remote | Repo URL comes from git remote origin unless you pass --repo-url |
| Pushed branch (typical) | With workOnCurrentBranch: true, the agent only sees commits already on the remote branch |
Optional: jq, curl (used by the helper script).
Quick start
From the repo root, after pushing the branch the agent should use:
export CURSOR_API_KEY=...
git push -u origin "$(git branch --show-current)"
./.ralph/scripts/start-cursor-cloud-session.sh \
--branch "$(git branch --show-current)" \
"Your task prompt here"
The script prints url=... and the session link on the last line. Capture that URL if you need to record it (e.g. append to a log file). Do not poll, stream, or wait for the run to finish unless the user explicitly asked you to watch this session.
Workflow
- Confirm intent — New cloud VM vs continuing an existing agent (follow-up runs use
POST /v1/agents/{id}/runs, not this skill).
- Prepare git — Checkout the integration branch;
git push so the cloud VM can pull it when using --work-on-branch (default).
- Start session — Run the helper script or
curl (see API below). The API returns immediately; work runs asynchronously on Cursor infrastructure.
- Record URL (if needed) — Save
agent.url where your workflow expects it (e.g. .ralph/sessions.log via ralph-chain-next.sh). Stop — do not monitor the run.
Ralph / recursive chaining
When ralph-chain-next.sh (or an iteration ending with chain-next) starts the next cloud session:
- Fire-and-forget — return as soon as the create API succeeds and you have the URL.
- Do not monitor, poll, or stream the next session from the current session.
sessions.log on the branch is the session registry for humans and later agents — not your chat transcript.
Optional: if a human is in the same interactive chat and asked for a link, you may paste the URL once. That is not required for Ralph workers chaining to the next VM.
Helper script options
./.ralph/scripts/start-cursor-cloud-session.sh --help
| Flag | Effect |
|---|
--branch NAME | repos[].startingRef (default: current branch) |
--work-on-branch / --no-work-on-branch | Push to starting ref vs new cursor/... branch (default: work on branch) |
--auto-pr | autoCreatePR: true |
--model ID | Model id (default = Auto) |
--env KEY=VAL | Session envVars (repeatable) |
API (manual)
curl -fsS -u "$CURSOR_API_KEY:" \
-H "Content-Type: application/json" \
-X POST https://api.cursor.com/v1/agents \
-d '{
"prompt": { "text": "…" },
"model": { "id": "default" },
"repos": [{ "url": "https://github.com/org/repo", "startingRef": "my-branch" }],
"workOnCurrentBranch": true,
"autoCreatePR": false
}'
Response fields to capture: agent.url, agent.id, run.id. Docs: Cloud Agents API.
In-app handoff (interactive CLI)
From a local Cursor CLI session, prefix a message with & to push work to the cloud without calling the API yourself. See Using Agent in CLI.
Related
- Recursive Ralph:
.ralph/scripts/ralph-chain-next.sh with "worker": "remote-cursor" in .ralph/ralph.config.json (see .ralph/README.md, ralph skill)
