Pairing

Pairing links OpenCompanion on this machine to one app. It uses device authorization (RFC 8628): the daemon asks the app to start a grant, you approve it in your browser while signed in to that app, and the daemon stores the resulting session locally (encrypted). No API key is copied or pasted, and the app never sees a credential of yours.

Pair with an app

opencompanion pair --url https://your-app.example/api

The --url is the app's API base (its origin plus API path), not the marketing site. opencompanion setup --url <app> runs this for you and then connects your CLIs and installs the service; use bare pair when you only want to add a pairing.

You can pair with more than one app. Every command that acts on a pairing takes --url to pick which one; with a single pairing --url is optional, and in a terminal with several pairings OpenCompanion asks which one you mean.

Connect a coding CLI

A pairing on its own dispatches nothing until a CLI is connected to it:

opencompanion connect                 # detect, install, and log in your CLIs
opencompanion connect claude-code     # just one

OpenCompanion detects, installs, and logs in Claude Code, Codex, and opencode for you. Hermes is system-installed only, so you install it yourself and the daemon connects to whatever is on your PATH. To stop the daemon driving one CLI while leaving it installed and signed in:

opencompanion disconnect claude-code

See what is paired

opencompanion backends     # device id, connected CLIs, ceiling, daemon state - per app
opencompanion status       # the lighter view: device id, and per app which CLIs are connected + auth health

backends is the full picture for each pairing: its device id, how many CLIs are connected, the capability ceiling that clamps its runs (see Policy), and whether the always-on daemon is running. status is the quick check on connection and auth health.

Remove a pairing

opencompanion unpair --url https://your-app.example/api

This drops the pairing and deletes its stored session from this machine. A running daemon notices and stops serving that app within one reconcile (about 15 seconds); no restart is needed. To remove everything at once, see Uninstall.

Every pair, unpair, and connect is written to the audit log.