cursor-cloud

name	cursor-cloud
description	Cloud runtime for Cursor SDK — dedicated VMs, repo-bound runs, auto-PR creation, artifacts, and reattachment. Use when running long, review-oriented, or repo-modifying agents off the local machine.
metadata	{"internal":false,"source":"https://cursor.com/docs/sdk/typescript"}

cursor-cloud

The cloud runtime gives each agent its own VM, persists across network drops, and can open PRs directly. Pass cloud (instead of local) on Agent.create.

When to use

• Long-running tasks (CI bots, scheduled refactors, kanban-driven PRs)
• Tasks that mutate a remote repo and produce a PR
• Multi-process orchestration where you reattach to a run from a different worker

Configuration

• [[references/cloud-options]] — full CloudOptions shape
• [[references/repos]] — repo refs, startingRef, existing-PR mode
• [[references/environments]] — env.type: "cloud", "pool", "machine"
• [[references/env-vars]] — session envVars
• [[references/auto-pr]] — autoCreatePR, workOnCurrentBranch, skipReviewerRequest

Outputs

• [[references/git-info]] — run.git branches and PR URLs
• [[references/artifacts]] — agent.listArtifacts() and downloadArtifact()

Lifecycle

• [[references/reattach]] — Agent.getRun(runId, { runtime: "cloud", agentId })
• [[references/durable-runs]] — runs survive disconnects; reattach with agentId+runId

Cross-links

• Local mode → [[../cursor-sdk/references/local-options]]
• Run interface → [[../cursor-runs/references/run-interface]]
• Errors → [[../cursor-errors/SKILL]]