Cursor Agent provider

The Cursor Agent provider delegates each agent to an in-process @cursor/sdk runtime. Like Codex, Cursor runs the work in its own engine with its own tool catalog, while Cerevisor supervises: wave orchestration and inter-agent handoff stay with Cerevisor.

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.
• 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 for the full cloud setup.

Permissions

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

Cerevisor	Cursor sandboxOptions.enabled
File write OR bash allowed	false (read-only mode disabled = useful work allowed)
Both file write AND bash blocked	true (read-only mode enabled = lockdown)

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

Known v1 limitations

• No mid-run continuation. A Cursor run can't be steered or continued mid-task; when Cerevisor's output check finds a problem, the retry runs as a fresh attempt. Cloud runs can be chatted with after they finish (the run persists on Cursor's servers and resumes with full context); local runs can't — use "Resume from this agent" to re-run instead.
• Cost reported as $0.00. Cursor's SDK doesn't surface token counts back to the caller for local runs, so Cerevisor can't compute spend even though Cursor bills your account per use.
• MCP tools. Cursor's SDK accepts an AgentOptions.mcpServers config, but Cerevisor does not pass its configured MCP servers through to Cursor runs today. 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.

Background features

Cursor has no plain streaming chat, but background features (run retrospectives, memory crystallization, skill summarization) still work when Cursor is your default: each call runs as one small Cursor agent task. If a call fails at runtime, Cerevisor automatically retries it on another chat-capable credential in your library and records any fallback spend in Analytics → Models.

The chat builder works two ways:

• Point it at a chat-capable provider (most reliable) — Settings → Chat Builder lets the builder run on a different provider than your agents.
• Run it on Cursor directly — turn on Settings → Chat Builder → "Build with a subscription provider." Each builder message becomes one Cursor agent task that emits the workflow changes. Slower and less precise than a chat-capable provider, and it uses your Cursor account, but it keeps everything on one provider.

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.