# Choosing Between Local and Cloud Runtime for Cursor SDK Agents

> The Cursor SDK currently only supports cloud runtime. Learn why and explore potential future options for local runtime execution.

- Repository: [Cursor/plugins](https://github.com/cursor/plugins)
- Tags: comparison
- Published: 2026-05-25

---

**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](https://github.com/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`](https://github.com/cursor/plugins/blob/main/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.

```typescript
// 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`](https://github.com/cursor/plugins/blob/main/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.

```typescript
// 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`](https://github.com/cursor/plugins/blob/main/orchestrate/skills/orchestrate/scripts/tools/probe-models.ts) at line 12, model availability checks hard-code `runtime: "cloud"`. The CLI commands in [`task.ts`](https://github.com/cursor/plugins/blob/main/task.ts) and [`inspect.ts`](https://github.com/cursor/plugins/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/cursor/plugins/blob/main/agent-manager.ts) and [`probe-models.ts`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/agent-manager.ts). You can test your orchestration logic locally, but the actual agent execution happens remotely.