Cursor Cloud

cursor_cloud runs Cursor Cloud Agents through the official Cursor SDK so ThinkingMach can keep task state while Cursor handles remote code execution. Use it when you want durable remote Cursor agent sessions that survive between ThinkingMach heartbeats.

When To Use

  • You want ThinkingMach to run Cursor Cloud Agents through the official Cursor SDK.
  • You want durable remote Cursor agent sessions across ThinkingMach heartbeats.
  • You want ThinkingMach to keep task state while Cursor handles remote code execution.

When Not To Use

  • You want local execution on the same machine as ThinkingMach. Use Cursor Local.
  • You do not have a Cursor API key or a Cursor account that allows cloud agents.
  • The work the agent needs to do cannot be expressed as a repository checkout.

Common Fields

Field Required Notes
repoUrl yes Git repository URL Cursor should open.
repoStartingRef no Starting ref for the repo.
repoPullRequestUrl no Pull request URL to attach the agent to.
runtimeEnvType no cloud, pool, or machine.
runtimeEnvName no Named cloud, pool, or machine target.
workOnCurrentBranch no Continue work on the current branch instead of cutting a new one.
autoCreatePR no Let Cursor auto-create a pull request.
skipReviewerRequest no Suppress the reviewer request on auto-created PRs.
instructionsFilePath no Agent instructions file prepended to the prompt.
promptTemplate no Heartbeat prompt template.
bootstrapPromptTemplate no First-run-only bootstrap prompt template.
model no Cursor model id. Omit to use the account default.
env.CURSOR_API_KEY yes Cursor API key. Use a ThinkingMach secret reference.
env.* no Additional environment variables injected into the cloud agent shell.

Session Persistence

ThinkingMach reuses the durable Cursor agent across heartbeats when the repo and runtime identity still match. Each ThinkingMach heartbeat maps to a Cursor run on that durable agent. If the repo URL, starting ref, or runtime environment changes, ThinkingMach starts a fresh Cursor agent.

Execution Details

  • ThinkingMach drives the agent through the Cursor SDK rather than a local CLI.
  • ThinkingMach injects THINKINGMACH_* runtime env vars into the cloud agent shell via the Cursor SDK cloud envVars channel.
  • ThinkingMach remains the source of truth for issue and task state. Cursor provides the remote execution surface.

Example

{
  "adapterType": "cursor_cloud",
  "adapterConfig": {
    "repoUrl": "https://github.com/example-org/example-repo",
    "repoStartingRef": "main",
    "runtimeEnvType": "cloud",
    "workOnCurrentBranch": false,
    "autoCreatePR": true,
    "skipReviewerRequest": false,
    "promptTemplate": "You are the engineering lead. Work carefully and report progress.",
    "bootstrapPromptTemplate": "Bootstrap the working environment, then await instructions.",
    "env": {
      "CURSOR_API_KEY": {
        "type": "secret_ref",
        "secretId": "secret-id",
        "version": "latest"
      }
    }
  }
}