Cursor Agent provider

The Cursor Agent provider delegates each agent to an in-process @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.
• 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
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.