Authentication

cursor-agent backend

The default backend uses the login owned by cursor-agent:

cursor-agent login

Check the session by asking the CLI for its model list:

cursor-agent models

Then confirm OpenCode sees the provider:

opencode models | grep cursor-acp

The two checks answer different questions. cursor-agent models confirms that Cursor accepts your login and shows which models your account can use. opencode models confirms that the plugin and provider configuration loaded.

OpenCode auth

You can also log in from OpenCode. On OpenCode 2.x:

opencode auth login

Choose Cursor, then Log in with cursor-agent (browser) or API key. The cursor-agent option connects at once when cursor-agent is already logged in; otherwise it runs cursor-agent login and shows Cursor's sign-in link. It stores nothing secret, and it works from /connect in the TUI and in OpenCode Desktop. On OpenCode 1.x, opencode auth login --provider cursor-acp stores an API key.

A stored key selects the SDK backend on OpenCode 2.x. Use a real key: if Cursor rejects it and cursor-agent is installed, open-cursor falls back to cursor-agent and logs a warning. Remove a bad key with opencode auth logout cursor-acp. Without an interactive terminal, add the credential label from opencode auth list, for example opencode auth logout cursor-acp Cursor.

SDK backend

Set a real Cursor API key from Cursor settings when using CURSOR_ACP_BACKEND=sdk:

export CURSOR_API_KEY=<your-api-key>
export CURSOR_ACP_BACKEND=sdk

The SDK path also reads an API key from the OpenCode auth store or from the apiKey option in the cursor-acp provider block.

Do not use the historical cursor-agent placeholder as an SDK key. The SDK requires a real key.

What a failed login looks like

Authentication failures usually surface as Not authenticated, fetch() URL is invalid, or a provider error before any response tokens arrive.

Run:

open-cursor doctor
cursor-agent models

If cursor-agent models fails, sign in again. If it succeeds but opencode models | grep cursor-acp returns nothing, check Troubleshooting.