Skip to content

setup.md

Latest commit

 

History

History
117 lines (90 loc) · 5.21 KB

setup.md

File metadata and controls

117 lines (90 loc) · 5.21 KB
Raw

Setup and activation

The claustrum-auth plugin is vault-only. Enrollment and grants belong to ck auth; provider activation happens inside the host, not in setup. It does not offer local sign-in or a local API-key store.

Preview or run setup

Quit OpenCode and Pi before making changes. The setup command is supplied by the OpenCode package and can register either public package:

npx @cortexkit/opencode-claustrum-auth setup

To preview setup without changing the host profile:

npx @cortexkit/opencode-claustrum-auth setup --dry-run --opencode=both

Run the same command with --yes instead of --dry-run to apply the plan. Setup uses common-auth's host detection, stopped-process fence, enrollment ceremony and registration. It never writes host credentials or starts a host server.

Useful flags:

  • --host opencode or --host pi: limit setup to one host family (the equals form also works).
  • --opencode=1, --opencode=2 or --opencode=both: select OpenCode versions.
  • --enroll-only: enroll without registering a host plugin.
  • --help: print the supported flags without running setup.

Vault mode is always on. --claustrum is accepted for compatibility; --no-claustrum and --login are refused with This plugin serves vault keys only.

Approve enrollment and grant access

Approve each host's separate enrollment in ck auth. The apps show "Model API keys for OpenCode" or "Model API keys for Pi" when you approve the connection. Setup requests read access to the llm-provider category with each enrollment, so approval grants that access in the same step on vaults that support requested grants. Setup checks access after approval and prints the resolved state paths and provider activation commands.

Older vaults may approve enrollment without applying the requested grant. If access is missing or cannot be confirmed, follow setup's printed grant command before activating a provider:

ck auth grant --principal enrolled:claustrum-auth-opencode --selector-kind category --selector llm-provider --operation read
ck auth grant --principal enrolled:claustrum-auth-pi --selector-kind category --selector llm-provider --operation read

Approve each additional instance of OpenCode or Pi with its own --name, and use that same name in the grant's --principal enrolled:<name>.

OpenCode and Pi use separate enrolled principals. A successful enrollment or grant for one is not a grant for the other. Keep credential creation and login refresh in the vault; the plugin consumes the served keys.

Activate in the host

After granting access, start the host and run the activation command printed by setup. Provider ids can differ across hosts; use the provider list, not the display name or a model id.

Host Activation
OpenCode 1 /claustrum use <provider> inside OpenCode
OpenCode 2 opencode auth login <provider> --method claustrum-auth
Pi /claustrum use <provider> inside Pi

OpenCode 2.2 runs auth login through a background server (opencode service status shows it). Quitting the OpenCode window doesn't stop that server, and it keeps the plugins it loaded when it started. If it was already running before setup, the login can't find the claustrum-auth method. Run opencode service restart once, or add --standalone to the login command, which runs that one login on a temporary server that reads your current configuration. Scripts should always add --standalone.

For example, Kimi Code is kimi-code-plan-global on OpenCode and kimi-coding on Pi. Serving a turn requires a model in the host's catalog and the plugin's provider and request checks to pass.

Pi asks for consent before moving an existing login aside. Activation and release preserve the host's ownership safeguards; they are not commands to overwrite another plugin's credentials. See commands and troubleshooting for ownership refusals.

Check the result

Run /claustrum status and /claustrum accounts inside the host. Confirm vault reachability, provider ownership and the accounts available for routing. Use /claustrum refusals for rows the plugin cannot serve. See provider metadata if a row is refused despite a successful grant.

Thalamus routing

When Thalamus supplies its routing accessor and the plugin's next row is an API key, routing chooses that request's vault API key, including for titles, compaction and retries, from the enabled accounts for that provider. The plugin never substitutes its own choice. A routing refusal stops the request with "Thalamus routing declined this request, so it was not sent." No answer stops it with "Thalamus routing did not answer, so this API key request was not sent." Slow routing (over 1.5 seconds) counts as no answer and stops the API-key request too. Documented empty-balance refusals are reported back to routing; user-set spending caps are not. Outside Thalamus, without its accessor, account selection is unchanged.

Subscription (OAuth) rows are not routed yet. If the plugin's usual next row is an OAuth login, it serves that login as before without asking routing; only an API-key attempt asks routing to choose among eligible API keys.