Choosing Between Local and Cloud Runtime for Cursor SDK Agents

Cloud runtime is the only supported execution environment for Cursor SDK agents in the current implementation, as the orchestrator hard-codes runtime: "cloud" in all SDK interactions and never passes runtime: "local".

The Cursor SDK defines two theoretical execution environments—cloud and local—but the actual implementation in the cursor/plugins repository exclusively supports cloud runtime. When building agents with the Cursor SDK, you must design for remote execution because the orchestrator assumes all agent workloads run in the cloud-hosted environment.

Understanding Cursor SDK Runtime Architecture

The SDK's type definitions technically allow specifying either "cloud" or "local" for the runtime parameter, but the orchestrator implementation makes cloud execution mandatory. According to the source code in cursor/plugins, every agent interaction defaults to cloud infrastructure regardless of local development context.

Cloud-Only Implementation Patterns in the Orchestrator

Agent Creation via Cloud Configuration

In orchestrate/skills/orchestrate/scripts/core/agent-manager.ts at lines 133-137, the Agent.create method is invoked with a cloud configuration object rather than a runtime flag. The method receives parameters defining repositories and starting refs, forcing remote execution by default.

// Lines 133-137 in agent-manager.ts
const agent = await Agent.create({
  apiKey,
  name: taskConfig.agent,
  model: taskConfig.model,
  cloud: {
    repos: [{ url: repoUrl, startingRef }],
    autoCreatePR: false,
  },
});

Run Retrieval with Hard-Coded Cloud Runtime

When querying agent status or recovering from crashes, the orchestrator explicitly passes runtime: "cloud" to Agent.getRun. At lines 66-69 in agent-manager.ts, the recoverRunning function retrieves run information using cloud-specific parameters. Similarly, the cancelCloudRun function at lines 111-113 specifies cloud runtime before cancelling operations.

// Lines 111-113 - Cancelling requires cloud runtime specification
const run = await Agent.getRun(runId, {
  runtime: "cloud",
  apiKey,
  agentId,
});
await run.cancel();

Utility Functions and CLI Tools

Even auxiliary tools enforce cloud execution. In orchestrate/skills/orchestrate/scripts/tools/probe-models.ts at line 12, model availability checks hard-code runtime: "cloud". The CLI commands in task.ts and inspect.ts filter and display only cloud runs, ensuring consistent behavior across the toolchain.

Local Runtime Limitations and Validation

Attempting to instantiate agents with runtime: "local" would trigger validation errors because no code paths in the orchestrator support this option. While the SDK's type system accepts the parameter, the server rejects requests for local execution. The orchestrator's AgentManager class contains no logic for spawning or managing local processes—all task execution flows through the cloud API.

Practical Code Examples for Cloud Runtime

Cancelling a Running Cloud Agent

To terminate an active agent, you must first retrieve the run using cloud runtime parameters:

import { Agent } from "@cursor/sdk";

async function cancelCloudRun(apiKey: string, agentId: string, runId: string) {
  const run = await Agent.getRun(runId, {
    runtime: "cloud",
    apiKey,
    agentId,
  });
  await run.cancel();
}

Creating and Spawning Cloud Agents

New agents automatically execute in the cloud when you provide the cloud configuration:

import { Agent } from "@cursor/sdk";

async function spawnWorker(apiKey: string, repoUrl: string, startingRef: string) {
  const agent = await Agent.create({
    apiKey,
    name: "my-project/worker-task",
    model: "gpt-4o-mini",
    cloud: {
      repos: [{ url: repoUrl, startingRef }],
      autoCreatePR: false,
    },
  });
  const run = await agent.send("Your prompt here");
  console.log(`Run ${run.id} started in cloud`);
}

Recovering After Script Restarts

If your orchestrator crashes, recover existing runs by specifying cloud runtime:

import { Agent } from "@cursor/sdk";

async function recoverRun(apiKey: string, agentId: string, runId: string) {
  const run = await Agent.getRun(runId, {
    runtime: "cloud",
    apiKey,
    agentId,
  });
  const result = await run.wait();
  console.log(`Run finished with status ${result.status}`);
}

Summary

• Cloud-only architecture: The cursor/plugins orchestrator exclusively uses runtime: "cloud" in all SDK interactions.
• Hard-coded runtime values: Files like agent-manager.ts and probe-models.ts contain no local execution paths.
• Validation constraints: While the SDK types allow "local", the server rejects these requests, making cloud runtime the only viable option.
• Agent creation patterns: All Agent.create calls use the cloud configuration object to define repositories and execution parameters.

Frequently Asked Questions

Can I run Cursor SDK agents locally?

No. Despite the SDK's type definitions allowing a runtime: "local" parameter, the cursor/plugins orchestrator contains no implementation for local execution. All agent creation, status queries, and cancellation operations hard-code runtime: "cloud".

What happens if I try to pass runtime: "local" to Agent.create?

The SDK would accept the parameter at the type level, but the server would reject the request with a validation error. The orchestrator never generates such requests because it assumes cloud infrastructure for all agent workloads.

How do I cancel a running cloud agent?

Use Agent.getRun with runtime: "cloud" to retrieve the run object, then call run.cancel(). As shown in orchestrate/skills/orchestrate/scripts/core/agent-manager.ts at lines 111-113, you must specify the cloud runtime and provide the agentId and runId to locate the remote process.

Is there any way to debug agents locally before deploying to the cloud?

Local debugging runs the orchestrator script itself, not the agent performing the task. The agent always executes in the cloud runtime according to the implementation in agent-manager.ts. You can test your orchestration logic locally, but the actual agent execution happens remotely.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}