Connector reference

Beta: the connector is an open package under the MIT license, published to npm after its security review. Frame names here are protocol version 1.

Commands

Command	What it does
`pair --url … --token oc_ct_…`	Swaps a one-time connect token for this machine's connector credential and stores it. The token is burned.
`install`	Registers the connector as a launchd (macOS) or systemd (Linux) user service so it keeps running.
`status [--json]`	Pairing, service, connection and the sessions it shares.
`uninstall [--forget]`	Stops and removes the service. `--forget` also deletes the stored credential.

Files

Path	Purpose
`~/.config/orpheus-connector/credential`	The connector credential (`oc_cc_…`), mode 0600. On macOS it is kept in the keychain instead.
`~/.config/orpheus-connector/policy.json`	Local policy: exposed sessions, input, transcripts, usage. Edited only on the machine.

Connection

The connector opens a secure WebSocket to /connect and sends Authorization: Bearer oc_cc_….
The server checks the credential's hash, its revocation flag and the workspace's server allowance.
Heartbeat every 20 seconds. On a drop, it reconnects with jittered backoff.
The credential rotates every 30 days over the open socket.
Frames are JSON and carry v: 1.

Frames: connector to Orpheus

Frame	Fields	Meaning
`hello`	os, hostLabel, version, caps	Sent on connect. Says what this connector is and can do.
`sessions`	list	The sessions the policy exposes.
`pane`	id, seq, data	Terminal output of a subscribed session, in order.
`transcript`	session, turns	Conversation turns for the chat view, if shared.
`live`	session, state	Whether a session is working or waiting.
`usage`	logins[]	Weekly and session percentage per login. Only when the local policy has `usage: true` (off by default).
`ask`		A question from an agent for you to answer.
`result`	reqId, ok, err	The outcome of a request from the server.

Frames: Orpheus to connector

Frame	Fields	Meaning
`subscribe` / `unsubscribe`	session	Start or stop streaming a session's output.
`send`	reqId, session, text, submit	Type text into an exposed session, and optionally press enter.
`key`	reqId, session, key	Press one key from the allowed list.
`transcript`	reqId, session, since	Ask for turns after a point.
`newSession`	name, cmd	Start a new agent session. `cmd` must be on the connector's allowed list.
`usageNow`		Ask for a usage reading now.

The connector checks every send and key against the local policy before acting, and answers with result.

Allowed keys

up down left right enter escape space tab bspace

What is not in the protocol

No exec frame. Input reaches your machine only as tmux send-keys into an exposed session.
No frame that edits the policy.
No file read or write frames.