Sophon

Pairing & installations

Pairing connects a Sophon account to one connector runtime. The result is an installation: a named connection that can receive messages, stream replies, run tools, and ask for approvals.

Installation model

One installation usually maps to one running connector:

Serafim's account
  ├─ Work Mac OpenClaw       inst_…
  ├─ Home Mac OpenClaw       inst_…
  └─ VPS custom connector    inst_…

Each installation has its own token, display name, permissions, health state, and chat sessions.

Browser pairing

The default OpenClaw flow is browser-based:

  1. User runs npx @sophonai/openclaw.
  2. The CLI opens a Sophon pairing URL.
  3. User signs in with Google if needed.
  4. User confirms the machine/runtime.
  5. The connector stores a scoped bridge token locally.
  6. iOS shows the new installation in the chat list.

This is the preferred flow for laptops and desktops because it avoids copying codes between terminal and phone.

Manual pairing

Headless or SSH environments can use a short code:

  1. Connector calls /v1/pairing/start.
  2. Connector prints the code.
  3. User opens iOS settings and enters the code.
  4. Connector polls /v1/pairing/poll and receives the token.

Manual pairing is useful for servers, remote shells, or environments where opening a browser is not possible.

Token scope

A bridge token is scoped to one installation:

inst_<id>:s_live_<secret>

It can call /v1/bridge/* for that installation and open the bridge WebSocket. It is not a user session token and should not be used by the iOS app or a browser.

Revocation and rotation

If a machine is lost or a token leaks:

  • revoke the installation,
  • delete the local credentials file or keychain entry,
  • pair again to issue a fresh token.

A revoked token can no longer connect to the bridge WebSocket or post message/task/approval events.

Naming

Installation names should describe the runtime or machine, not pretend to be a public agent brand. Good examples:

  • Work Mac OpenClaw
  • Home Mac coding agent
  • Prod support connector

Avoid names like OpenAI, Claude, or Official Support unless that is actually the verified connector you operate.

Read next