pi-cursor-cloud-api

Run pi-subagents jobs as durable Cursor Cloud Agents through Cursor's public REST API v1.

This package does not use @cursor/sdk and does not depend on pi-cursor-sdk. Pi remains the parent orchestrator. Cursor owns the remote workspace, model execution, branch, and pull request.

Early alpha: the source has been reviewed against Cursor's public OpenAPI contract, but no authenticated live API run has been performed yet.

What it provides

• A packaged cursor-cloud subagent for pi-subagents
• Direct Bearer-authenticated calls to https://api.cursor.com/v1
• Automatic GitHub origin and current-ref discovery
• Dirty-worktree and unpushed-commit protection
• Deterministic bc-<uuid> agent IDs for idempotent initial dispatch
• Durable status, result retrieval, reattachment, and follow-up runs
• New branch plus automatic pull request by default
• Explicit cancellation with /cursor-cloud-cancel
• Live model discovery with /cursor-cloud-models

Requirements

• Node.js 22.19 or newer
• Pi with pi-subagents 0.55.0 or newer
• A Cursor API key from the Cursor dashboard
• Cursor's GitHub App connected to the repository you want the cloud agent to edit

Cursor Cloud Agents execute remotely and consume Cursor usage. Review Cursor's current plan, spending, and API terms before dispatching work.

Install

pi install npm:pi-subagents
pi install npm:pi-cursor-cloud-api

Until the first npm release is published, install the current GitHub version:

pi install git:github.com/GatienBoquet/pi-cursor-cloud-api

After the v0.1.0 GitHub release exists, append @v0.1.0 to pin that release.

Set the API key in the environment that launches Pi.

PowerShell:

$env:CURSOR_API_KEY = "your-cursor-api-key"
pi

macOS or Linux:

export CURSOR_API_KEY="your-cursor-api-key"
pi

Do not place the key in agent frontmatter or commit it to a repository.

Use

From a clean Git repository whose current branch is pushed:

Use cursor-cloud to add installation instructions to the README.

The packaged profile discovers origin and the current branch from the subagent job directory. By default Cursor creates a new cursor/... branch and opens a pull request.

Check the run through normal pi-subagents status and wait actions. A completed result includes Cursor's final response, pushed branches, pull request URLs, and duration.

Agent options

Create a user or project agent when you need explicit settings:

---
name: cursor-cloud-plan
description: Ask Cursor Cloud to investigate a repository and produce a plan
runner:
  type: external-job
  provider: cursor-cloud-api
  options:
    repo: https://github.com/OWNER/REPOSITORY
    startingRef: main
    mode: plan
    autoCreatePR: false
    workOnCurrentBranch: false
async: true
---

Investigate the request in the repository and return a concrete implementation plan. Do not edit files.

Supported options:

| Option | Default | Purpose | | --- | --- | --- | | repo | local origin | One GitHub repository URL | | repos | none | Explicit API-compatible repository array, maximum 20 | | startingRef | current local ref | Starting branch or commit | | prUrl | none | Continue work on an existing GitHub pull request | | model | Cursor default | Model ID, or { id, params } from /cursor-cloud-models | | name | API-generated | Cursor agent display name | | env | Cursor default | cloud, pool, or machine environment selection | | mode | API default | agent or plan | | autoCreatePR | true | Open a pull request after successful work | | workOnCurrentBranch | false | Push directly to the selected ref when enabled | | skipReviewerRequest | false | Do not request the API-key owner as PR reviewer | | allowDirty | false | Allow dispatch while local changes are invisible to Cursor | | allowUnpushed | false | Allow a local ref Cursor may not be able to fetch | | skipLocalPreflight | false | Disable all local Git safety checks | | noRepo | false | Start a repository-free Cloud Agent |

For multiple repositories, put startingRef and prUrl inside each repos entry.

Follow-up runs

The provider implements followUp(). Resume a completed external-job run through the normal pi-subagents resume action. The new prompt is sent to:

POST /v1/agents/{agentId}/runs

The same Cursor conversation and remote workspace are retained.

Cancellation

Cursor exposes run cancellation, while the current pi-subagents external-job bridge does not yet delegate its normal stop action to providers. Use the provider job ID shown by subagent status:

/cursor-cloud-cancel cursor-v1.<encoded-job-identity>

The command calls:

POST /v1/agents/{agentId}/runs/{runId}/cancel

The provider also exposes cancel(providerJobId) as an extra method so a future pi-subagents release can adopt it without changing this package's public contract.

Safety model

• The Cursor API key is read lazily from CURSOR_API_KEY or CURSOR_CLOUD_API_KEY.
• Secrets are not accepted in persisted runner options.
• The default create request supplies a deterministic agent ID. If the first network response is lost, a repeated dispatch recovers the existing agent and latest run instead of creating a second agent.
• An ambiguous create failure, including a client timeout after Cursor accepted the request, is recovered by looking up that deterministic agent ID. Explicit API failures such as authentication or rate-limit errors still fail closed.
• Dirty files and unpushed commits fail closed because a remote agent cannot see them.
• Direct pushes are disabled unless workOnCurrentBranch: true is explicit.
• Status requests are cached for three seconds by default to avoid forwarding pi-subagents' one-second polling interval directly to Cursor. Set CURSOR_CLOUD_STATUS_CACHE_MS between 1000 and 30000 to change it.

Session envVars, inline MCP credentials, images, artifacts, and SSE event rendering are intentionally not exposed in the first release. This keeps idempotent dispatch and secret handling narrow. They can be added behind explicit options later.

API status mapping

| Cursor run | pi-subagents state | | --- | --- | | CREATING | queued | | RUNNING | running | | FINISHED | completed | | ERROR | failed | | CANCELLED | stopped | | EXPIRED | failed |

Development

The extension is plain TypeScript executed by Pi's package loader. It uses Node's built-in fetch, crypto, and child_process modules, with Zod validating external data at runtime. No SDK or generated client is required.

Run the local quality gates and inspect the release contents with:

npm run check
npm pack --dry-run
pi -e .

Cursor Cloud Agents API v1 is in public beta. Keep request fields narrow and review the official endpoint documentation and OpenAPI specification before publishing compatibility changes.

License

MIT