---

name: add-cursor description: Use Cursor (local Agent SDK) as a full agent provider — planning, tool orchestration, MCP tools, session resume — alongside or instead of Claude. Cursor-account sign-in or API key, held by the credential gateway. Per-group via ncl groups config update --provider cursor. Distinct from using Cursor as a cloud agent (those run on Cursor VMs and are not this provider). metadata: nanoclaw-provider: cursor nanoclaw-provider-label: Cursor nanoclaw-provider-hint: Cursor — account sign-in or API key nanoclaw-provider-offered: 'true' nanoclaw-provider-image: local-required

Cursor agent provider

Shortcut: pnpm exec tsx setup/index.ts --step provider-auth cursor performs this whole install (payload files, barrels, SDK pin, image rebuild) plus auth in one command. The steps below are the same operations, for agent-driven or manual application.

NanoClaw selects each group's agent backend from container_configs.provider (default claude). This skill installs the Cursor provider: copy the payload from this skill's payload/, append one import to each of the five provider and contract barrels, pin @cursor/sdk in the agent-runner tree, rebuild, then run the auth walk-through.

The provider runs @cursor/sdk in-process inside the container (Agent.create / resume / send): native streaming, MCP tools, a local agent store (the continuation is a Cursor agentId). It integrates through the provider contracts only — a data-only host contract declares the composed AGENTS.md, the per-group .cursor-shared state volume at ~/.cursor, the two Cursor-native skill directories and the Cursor model domains; the runtime contract declares the execution stance, model mapping, memory hooks, MCP mapping, and archives each exchange into conversations/ through core's shared exchange archive.

Credentials stay in the credential gateway selected by NANOCLAW_GATEWAY_PROVIDER. The container only ever sees the placeholder CURSOR_API_KEY=curs…[redacted], which the SDK sends as a bearer header. Setup stores the key for two exact routes: api2.cursor.sh/auth/exchange_user_api_key, where the SDK swaps it for a short-lived runtime token, and api.cursor.com/v1/models, for model discovery. The runtime token stays in the SDK's memory and rides the same gateway proxy on the agent's Connect RPCs to api2.cursor.sh, which the gateway leaves untouched because the key is scoped to the exchange path. The payload ships cursor.gateway-proxy.test.ts, which proves every request of a real SDK run transits the proxy carrying nothing but the placeholder. Never put a key in chat.

The mechanical steps under Install carry nc: directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Install

Pre-flight

Install and refresh require host contract version 1, credential-connection seam version 2 or later (path-scoped credentials), and core's shared exchange archive (container/agent-runner/src/provider-contracts/exchange-archive.ts). The compatibility predicate below guards every later step, so an unsupported core receives no partial payload or dependency changes. If it prints no, stop and tell the operator to run /update-nanoclaw first.

node -e "const fs=require('fs'); const r=(f)=>fs.existsSync(f)?fs.readFileSync(f,'utf8'):''; if(/PROVIDER_HOST_CONTRACT_SEAM_VERSION = 1/.test(r('src/provider-contracts/registry.ts')) && /PROVIDER_CREDENTIAL_CONNECTION_SEAM_VERSION = ([2-9]|[1-9][0-9])/.test(r('setup/gateways/credential-store.ts')) && /export function archiveProviderExchange/.test(r('container/agent-runner/src/provider-contracts/exchange-archive.ts'))) console.log('yes'); else console.log('no')"

1. Copy the payload

Copy only the files listed below from this skill's payload/ to the matching paths at the project root. These are skill-owned files; overwrite them together when refreshing the skill. The host files are the data-only host contract, the env adapter and their guards; the container files are the provider runtime (turn loop, event mapping, hooks.json writer), the runtime contract, the memory hook adapter, the host-side login helper, and their guards — including the conformance test the verifier requires and the gateway-proxy proof; the setup file is the picker entry and auth walk-through.

payload/src/providers/cursor.ts -> src/providers/cursor.ts
payload/src/providers/cursor-registration.test.ts -> src/providers/cursor-registration.test.ts
payload/src/providers/cursor-host-contribution.test.ts -> src/providers/cursor-host-contribution.test.ts
payload/src/provider-contracts/cursor.ts -> src/provider-contracts/cursor.ts
payload/container/agent-runner/src/providers/cursor.ts -> container/agent-runner/src/providers/cursor.ts
payload/container/agent-runner/src/providers/cursor-auth.ts -> container/agent-runner/src/providers/cursor-auth.ts
payload/container/agent-runner/src/providers/cursor-hook.ts -> container/agent-runner/src/providers/cursor-hook.ts
payload/container/agent-runner/src/providers/cursor-gateway-probe.ts -> container/agent-runner/src/providers/cursor-gateway-probe.ts
payload/container/agent-runner/src/providers/cursor-registration.test.ts -> container/agent-runner/src/providers/cursor-registration.test.ts
payload/container/agent-runner/src/providers/cursor.factory.test.ts -> container/agent-runner/src/providers/cursor.factory.test.ts
payload/container/agent-runner/src/providers/cursor-auth.test.ts -> container/agent-runner/src/providers/cursor-auth.test.ts
payload/container/agent-runner/src/providers/cursor-hook.test.ts -> container/agent-runner/src/providers/cursor-hook.test.ts
payload/container/agent-runner/src/providers/cursor.poll-loop.test.ts -> container/agent-runner/src/providers/cursor.poll-loop.test.ts
payload/container/agent-runner/src/providers/cursor.conformance.test.ts -> container/agent-runner/src/providers/cursor.conformance.test.ts
payload/container/agent-runner/src/providers/cursor.gateway-proxy.test.ts -> container/agent-runner/src/providers/cursor.gateway-proxy.test.ts
payload/container/agent-runner/src/provider-contracts/cursor.ts -> container/agent-runner/src/provider-contracts/cursor.ts
payload/setup/providers/cursor.ts -> setup/providers/cursor.ts
payload/setup/providers/cursor.test.ts -> setup/providers/cursor.test.ts
payload/setup/providers/cursor-registration.test.ts -> setup/providers/cursor-registration.test.ts

2. Wire the barrels

Append import './cursor.js'; once to each of the five setup, provider, and contract barrels below. Keep all existing imports. Each barrel-registration test imports its real barrel and asserts cursor is registered.

import './cursor.js';

import './cursor.js';

import './cursor.js';

import './cursor.js';

import './cursor.js';

3. Agent-runner dependency

The container talks to Cursor through @cursor/sdk, not a CLI binary. Pin the exact version in the agent-runner tree (Bun, not the host pnpm workspace — @cursor/sdk must not enter the host lockfile). Do not add a Cursor CLI to container/cli-tools.json.

@cursor/sdk@1.0.28

4. Build and test

pnpm run build

cd container/agent-runner && bun run typecheck

pnpm exec vitest run src/providers/cursor-registration.test.ts src/providers/cursor-host-contribution.test.ts setup/providers

cd container/agent-runner && bun test --isolate src/providers/cursor*.test.ts

pnpm exec tsx scripts/provider-contract-verifier.ts --required-declared cursor

The verifier runs the host and runtime contract suites (registration, conformance, the gateway-proxy proof) and checks the host and runtime contract inventories agree. It goes red if a barrel line is missing, a barrel fails to evaluate, the payload is broken, or @cursor/sdk is not installed.

Build the local image. The SDK dependency requires a full local build.

./container/build.sh build

Authenticate

pnpm exec tsx setup/index.ts --step provider-auth cursor

The same walk-through fresh installs get from the setup picker: sign in with a Cursor account (browser or URL), or enter a Cursor API key into the local masked prompt. Account sign-in runs the host-side helper (bun container/agent-runner/src/providers/cursor-auth.ts), which uses Cursor.auth.login({ store: null }) to mint an expiring NanoClaw key into a mode-0600 handoff file; setup hands it to the credential gateway and deletes the file. The key is never printed, placed in process arguments, or sent through chat. The flow stores the key for those two routes, short-circuits only when the gateway already holds both, and finishes with the install check.

OAuth-minted keys default to 90 days; dashboard and service-account keys last until revoked. Prefer a dashboard or service-account key for unattended installs. To replace an expired or revoked key, remove both entries (Cursor for api2.cursor.sh/auth/exchange_user_api_key, Cursor models for api.cursor.com/v1/models) with your gateway's own tools, then re-run the provider-auth command.

Use it

After installing on a running NanoClaw host, restart the host service first so it loads the Cursor registration (Linux: systemctl --user restart nanoclaw-v2-<install-slug>.service; macOS: its launchd restart). A host that still runs the old build spawns Cursor groups without the Cursor state volume, so continuations would not survive a container restart.

Then, per group:

ncl groups config update --id <group-id> --provider cursor
ncl groups restart --id <group-id>

Switching is an operator action — run it from the host. Every provider uses the same memory/ tree, so memory carries across automatically. Run /migrate-memory only when upgrading a group that still has legacy .seed.md, CLAUDE.local.md, or unindexed imported memory. See docs/provider-migration.md.

--model selects the Cursor model (default composer-2.5). Cursor exposes no reasoning-effort or speed knob the container can map, so --effort is ignored and --speed is not accepted for cursor groups.

Default new groups to cursor (optional)

New groups are created on the instance default (DEFAULT_AGENT_PROVIDER in .env, or claude when unset). Installing this skill wires cursor in but does NOT change that default — "installed" is not "authenticated", so the default stays claude until you opt in explicitly.

After install, ask the operator before flipping it:

"Cursor is installed. Default new agent groups to cursor? Existing groups keep their current provider."

On yes — set it, then restart the host service as in Use it above so it takes effect:

pnpm exec tsx setup/index.ts --step set-env -- --key DEFAULT_AGENT_PROVIDER --value cursor

This affects only groups created afterward. Per-group `ncl groups config