The cursor backend

For whoever seats the cursor backend on a machine and writes the orders that run on it.

After reading it you can name a cursor model correctly in an order, log a cursor seat in or give it a key, have it seated, and act on every refusal a cursor spawn can give you.

Before you start: an admitted machine (saphan machine admit) and an account with the vendor of cursor-agent.

What it runs

The cursor backend drives Cursor's command-line agent, cursor-agent. Cursor's installer puts the same program on disk under two names, cursor-agent and agent; the engine runs the absolute path you register for the machine and never looks the program up on PATH.

Naming a model and its effort

An order names the model without an effort, and the effort on its own line — exactly as for every other backend:

- backend: cursor
- model: grok-4.7
- effort: high

The cursor-agent CLI has no effort switch: it spells the model and the effort as one id. The engine composes that id for you — model grok-4.7 with effort high runs as --model grok-4.7-high.

• ⛔ Never type the effort into the model (- model: grok-4.7-high). The effort is a separate setting, and a price row matches the model without it, so one grok-4.7 row prices every effort.
• ⛔ Never use the bracket form grok-4.7[effort=high]. Cursor's own help shows it for another model; for Grok, the vendor refused it.
• ⛔ Never pick a -fast variant.
• ⛔ auto is refused (cursor-leg-token-forbidden): Cursor resolves it on its side to another vendor's model, so the run would not run the model the order pinned.

The efforts an order may name for Cursor: low, medium, high, xhigh. Anything else is refused order-effort-not-accepted before any spawn.

Where the effort comes from, first to last: --effort, the order's - effort:, then the configured default dispatch.effort.<role>.cursor — for an executor, dispatch.effort.executor.cursor. A default model is dispatch.model.<role>.cursor; with one set, an order may name only - backend:.

Which models a cursor run may use is a list you keep, and a pair not on it is refused at dispatch:

saphan config show                                   # read the current list first
saphan config set probe.model.cursor grok-4.7        # the value REPLACES the whole list

⚠ The value replaces the list, so write every id you still want. The ids are the ones HOME=<seat home> cursor-agent --list-models prints, with the effort suffix removed.

⚠ There is no rehearsal of this check today. saphan dry-run dispatch place is refused (dry-run-no-rehearsal-path), and saphan dispatch check --model checks only the capability catalogue, so it passes a model the accepted list will refuse. Read saphan config show before you hand an order over.

Where it runs, and where it is confined

What the jail grants inside the seat's home is only what cursor-agent was measured writing there: .cursor, .npm, and the data directory the engine points Cursor at.

⚠ Not covered, and not measured rather than known harmless: cursor-agent also writes session logs and run markers in the system temporary directory. Those writes are not granted, and whether denying them affects a turn has not been measured.

⚠ The prompt rides the cursor-agent command line. A brief that makes the composed prompt 131 072 bytes or longer is refused cursor-prompt-too-large-for-argv.

Attribution is off: the agent signs none of your commits

Before every cursor spawn — local or remote, behind the proxy or not — the engine sets two keys in the seat's own Cursor settings file, <seat home>/.cursor/cli-config.json:

attribution.attributeCommitsToAgent = false
attribution.attributePRsToAgent     = false

Every other key of that file is kept. So a commit or a pull request made by a cursor run carries no co-author trailer naming the agent — the cursor-agent CLI was found set to attribute on every seat, and this is why the engine writes the setting itself rather than trusting the seat.

If the engine cannot read that file as JSON, or cannot write it, the spawn is refused cursor-seat-http1-unavailable (the same refusal guards the HTTP/1.1 key a run behind the proxy needs), and the refusal names the keys. Repair or remove the file — a file holding valid JSON, or no file at all, is accepted — and dispatch again.

How a cursor seat authenticates

The platform of the machine that runs the leg decides it:

⛔ There is no fallback. A macOS cursor seat with no key is refused, never run on whatever login the machine happens to hold. And the dispatcher's own CURSOR_API_KEY never reaches a run: the run's environment is built, not inherited, and --env CURSOR_API_KEY is refused by name.

The ceremony for a cursor seat, numbered

Every step here is a human act. Steps 2 and 3 are the owner's.

Install and seat (once per seat)

1. Install Cursor's CLI at the pinned version (2026.10.14-941492e) on the machine that will run the seat. ⚠ The vendor's own installer installs the newest version, and a seat on any other version is refused cursor-version-skew.

2. Register the program's absolute path for that machine — an owner act, confirmed with a one-time code:

   saphan machine set-binary --machine <machine-id> --binary cursor=<absolute path of the program on that machine>

   Skip this if saphan machine list already shows a cursor program for the machine, or if you passed the same --binary cursor=… to saphan machine admit.

3. Seat it — the owner's act, signed with the root key. A cursor seat's profile directory is its home: Cursor keys its login on $HOME, so --config-dir is the home the engine binds every time it spawns or logs in that seat.

   saphan machine seat --machine <machine-id> --slot <n> --identity <seat> \
     --backend cursor --config-dir <the seat's home on that machine> \
     --billing-class subscription --added-by <owner>

4. Accept the model if it is not already on the list: saphan config set probe.model.cursor <every id you want>.

Then follow one of the two acts below, by the seat's platform.

Log a Linux seat in (the first time, and whenever the engine says the login ended)

5. From a terminal, run:

   saphan machine login --workspace <canonical root> --machine <machine-id> --identity <seat>

   The engine runs <registered program> login under the seat's own home — in place for a local seat, over its own ssh connection with a terminal for a remote one — so you never type a path or ssh anywhere yourself. It prints the HOME=<value> it bound, which is the same value every spawn of the seat binds. Without a terminal it is refused machine-login-no-operator.

6. Complete the flow cursor-agent prompts for: open the URL it prints in a browser on your own machine, finish there, and let the CLI exit. A non-zero exit is refused machine-login-abandoned, and nothing is written.

7. Read the verdict. The engine then sends one short real prompt under the same home — it costs one small model turn on the seat's allowance. ALIVE is the only pass; anything else is refused machine-login-unverified and names what to do. Cursor's own status command is not used: it reads a cached login and can report "logged in" over a login the vendor no longer accepts.

8. Tell the record: run the saphan seat auth-performed --identity <seat> --machine <machine-id> --by <person> line the verb prints. It does not write that entry itself.

To measure a seat later without logging in again, add --verify-only to step 5's line; it sends the same one prompt.

Give a macOS seat its key

saphan machine login on a macOS Cursor seat is refused by name, and the refusal points here.

5. Create a key in the vendor's dashboard and copy it once; the dashboard will not show it again. ⚠ Two seats may share one key, but then they are one identity to the vendor — give each seat its own entry name in step 6 either way.

6. Add the key to credentials.json on the machine that runs the leg — the file the credentials.file row of saphan config show names, mode 0600, a flat object of strings (Secrets):

   { "CURSOR_SEAT_1_KEY": "<the key from step 5>" }

   ⛔ Never paste the key on a command line or into a configuration key: a shell history is a file.

7. Name the entry on the seat — the entry's name, never the key:

   saphan config set seat.<seat>.credential CURSOR_SEAT_1_KEY

8. Check without spending: saphan config show lists seat.<seat>.credential with its value redacted. Do not dispatch a test turn to check the key — it spends the seat's allowance; the first real dispatch is the proof.

Rotating or revoking: replace the value in credentials.json; the next dispatch reads it fresh. Revoke it in the vendor's dashboard.

⚠ A key reaches a run only on a local run. A key-based seat reached over ssh is refused cursor-seat-credential-transport, because the remote command line has no carrier that puts a key in the run's environment alone.

When a spawn is refused

What this page does not prove

• ⚠ A completed confined model turn on macOS is not yet in the evidence; the macOS confinement is rehearsed up to the cursor-agent sign-in check.
• ⚠ A remote Mac is not claimed as confined, and no such seat has been run.
• ⚠ Whether cursor-agent renews an expired login by itself is not measured. The engine refuses an expired login rather than find out; if it does renew, that refusal is stricter than it needs to be.
• ⚠ A newer cursor-agent CLI is refused until the pinned version is measured again — the flags, the output shape and the refusals above are read from one generation.