---
title: "Cursor Agent provider"
description: "Use Cursor's in-process SDK as a Cerevisor provider, local and cloud execution, API key auth, the limits to know about."
slug: guides/providers/cursor-agent
section: guides
subsection: providers
canonical_url: https://cerevisor.com/docs/guides/providers/cursor-agent
last_verified: 2026-05-18
last_verified_version: "1.2.0"
updated_at: 2026-05-18T15:08:18.053416+00:00
---

The **Cursor Agent** provider delegates each agent to an in-process [`@cursor/sdk`](https://www.npmjs.com/package/@cursor/sdk) runtime. Like Codex, Cursor owns the agentic loop and tool catalog; Cerevisor still owns wave orchestration and inter-agent handoff.

Why use it: you have a Cursor account and want to run agents through their SDK (typed, in-process, no subprocess), with optional cloud execution that survives Cerevisor restarts.

## Prerequisites

- A Cursor account with an API key from [cursor.com/dashboard](https://cursor.com/dashboard).
- The `@cursor/sdk` npm package installed alongside Cerevisor. It's an **optional dependency** so Cerevisor builds and runs without it: but if you want the Cursor provider, you need it.

## Setup wizard

1. **Settings → Providers → + Add provider → Cursor Agent.**

The wizard runs three steps:

### 1. Detect
Cerevisor tries to `require('@cursor/sdk')`. If it's not installed, you'll see an install hint.

### 2. API key + validate
Paste your Cursor API key. Click **Validate**, Cerevisor calls Cursor's identity endpoint to confirm.

### 3. Smoke test
Cerevisor spins up a trivial Cursor agent (`Agent.prompt`) to confirm the runtime works end-to-end.

Save and you're done.

## Local vs. cloud

Cursor supports two execution modes:

| Mode | Where it runs | Use when |
|---|---|---|
| **Local** | In-process via the Cursor SDK on your machine. | Most cases. Standard agent run, completes when Cerevisor is running. |
| **Cloud** | On Cursor's VMs. | Long-running runs. Survives Cerevisor restarts and laptop sleep. |

Toggle the run mode per workflow in **Settings → Workflow → Run mode** (Local / Cloud). Cloud mode is only valid when the active provider is `cursor-agent`. See [Cursor cloud runs](../advanced/cursor-cloud-runs.md) for the full cloud setup.

## Permissions

Cerevisor's `WorkflowPermissions` map to Cursor's sandbox options:

| Cerevisor | Cursor `sandboxOptions.enabled` |
|---|---|
| Filesystem write Allow | `false` (read-only mode disabled = writes allowed) |
| Filesystem write Ask/Deny | `true` (read-only mode enabled = writes blocked) |

Same up-front-only limitation as Codex CLI: per-tool `PermissionModal` doesn't intercept individual Cursor tool calls.

## Known v1 limitations

- **No chat surface.** `Agent.send` can't resume mid-tool-call. The chat builder, retrospectives, and other background features can't use Cursor. Configure a separate provider for background use.
- **Cost reported as `$0.00`.** Cursor's SDK doesn't surface token counts back to the caller for local runs. Analytics classifies these as "api-key" billed sessions.
- **MCP tools.** Cursor's SDK accepts an `AgentOptions.mcpServers` config, but Cerevisor does not pass its configured MCP servers through to Cursor runs in v1.2.0. If you need MCP tools inside a Cursor agent, configure them on the Cursor side directly. Sharing Cerevisor's MCP client into Cursor is on the roadmap.
- **No verifier retry.** Like Codex, output-verifier retry is disabled (`agent_verifier_skipped` reason `cursor-agent-no-resume`).

## Background features

Cursor can't drive the chat builder, run retrospectives, memory crystallization, or skill summarization. If your default is Cursor, configure a separate provider for background use:

- **Settings → Chat Builder**: set a different provider.
- Set the Anthropic or OpenAI-compatible provider as the library default for the other background features. The chat builder respects its own override; the rest fall back to the library default.

## When to prefer Cursor over Codex

- You're already a Cursor user.
- You want cloud execution that survives Cerevisor restarts (Cursor has this; Codex doesn't).
- You want an in-process runtime (no subprocess, no Windows `.cmd` shim trap).

## When to prefer Codex over Cursor

- You're a heavy ChatGPT user with a subscription you want to amortize.
- You don't want to pay per token (Codex's subscription model vs. Cursor's per-token).
- You prefer OpenAI's models over Cursor's curation.