can1357--oh-my-pi/docs/collab.md

Collab: Live Session Sharing

/collab shares your running session with other omp instances in real time. Guests render the same session natively in their own TUI — streaming assistant text, tool-call cards, footer state (cwd, model, context %, cost), ctrl+o expansion, /dump — no terminal mirroring. Guests can prompt and interrupt the agent; the host machine runs the agent and all tools.

Quick start

Host:

/collab

prints

Collab session started!
 • Join from another terminal: omp join "mgAYTZwEnpRQtca0CTgn-Q.gdJUbTovD94ofDaa8YvhY0-ty16w4fn8PgB6PLnoA30"
 • or any web browser: my.omp.sh/#mgAYTZwEnpRQtca0CTgn-Q.gdJUbTovD94ofDaa8YvhY0-ty16w4fn8PgB6PLnoA30

The browser line is click-to-join (an OSC 8 hyperlink to the full https:// deep link): the relay serves the web guest client at /, and the room id + key ride in the URL fragment. From another omp (any directory, any machine), either form works:

Running /collab or /collab view starts or displays the active hosting session, rendering both the terminal/browser join links and their corresponding QR codes.

/join my.omp.sh/#mgAYTZwEnpRQtca0CTgn-Q.gdJU…

The guest's previous session is restored on /leave (or when the host stops).

Commands

Command	Effect
/collab	Start sharing full-control (or re-print the link/QR when already hosting)
/collab <relay>	Start sharing through a specific relay (relay.example.com, ws://localhost:7475)
/collab view	Start sharing read-only (or re-print the link/QR when already hosting)
/collab status	Show link + participants
/collab stop	Stop sharing
/join <link>	Join a shared session as a guest
/leave	Leave (guest) or stop sharing (host)

Link format

Accepted by /join <link> and omp join "<link>":

<roomId>.<key>                                                    → default relay (wss://my.omp.sh)
<roomId>#<key>                                                    → legacy bare form
host[:port]/r/<roomId>.<key>                                     → custom relay, wss:// inferred
host[:port]/r/<roomId>#<key>                                     → legacy direct relay form
https://host[:port]/r/<roomId>.<key>                             → direct relay URL, normalized to wss://
wss://host[:port]/r/<roomId>.<key>                               → direct websocket relay URL
ws://localhost:7475/r/<roomId>.<key>                             → direct plain ws, localhost only
https://host[:port]/#<link>                                      → browser deep link when web UI and relay share a host
https://web-host[:port][/<path>]/#<relay-link>                   → browser UI wrapper with relay link in the fragment
https://web.example/collab/#relay.example.com/r/<roomId>.<key>   → web UI and relay on different hosts

<link> / <relay-link> are parsed recursively as any accepted link above. For http(s) browser wrappers with a parseable fragment, the fragment wins before the HTTP host/path are treated as a relay. This lets https://web.example/collab/#relay.example.com/r/<roomId>.<key> open the web UI at web.example while joining wss://relay.example.com/r/<roomId>. If the fragment is not a complete collab link, parsing falls back to the legacy direct relay form, so https://relay.example.com/r/<roomId>#<key> still means relay relay.example.com.

The trailing .<key> or #<key> part is the room secret, base64url-encoded, in one of two strengths:

• Full link — 48 bytes: the 32-byte AES-256-GCM room key followed by a 16-byte write token. Grants prompting, interrupting, and subagent control.
• View-only link — the bare 32-byte key, no write token. Grants live read access only. Pre-token links parse as view-only.

The room secret is dot-joined in newly generated links because RFC 3986 forbids a raw # inside a URL fragment; parsers still accept legacy # forms and %23-mangled legacy deep links.

End-to-end encryption

Every session payload (entries, events, state, prompts) is sealed with AES-256-GCM before it touches the socket. The relay sees only:

• room ids and connection counts,
• opaque ciphertext frames and their sizes,
• a 4-byte routing prefix (which guest a frame targets).

Possession of the link is the trust boundary: a full link reads and steers the session, a view-only link reads it. Share both like secrets.

Guest permission model

Two trust levels, enforced by the link itself — the host verifies the 16-byte write token at join and rejects writes from peers without it (they appear as read-only in the participants list, and the join notice says so).

Guests with a full link can:

• read the entire session (including the back-transcript at join time),
• prompt the agent (rendered with their name badge on every participant's transcript; the LLM sees the prompt text verbatim — names are display-only),
• interrupt the agent (Esc),
• use the Agent Hub against the host's subagents: live table and progress, chat (steers the host's subagent), kill, revive, and transcript viewing (fetched from the host on demand).

Guests with a view-only link can read everything live — back-transcript, streaming text, tool cards, subagent transcripts — but the host rejects prompting, interrupting, and agent control from them.

Everything that mutates the host session or machine is host-only: /model, /compact, /resume, /branch, bash (!), python ($), skills, etc. Guests keep a small local allowlist (/dump, /export, /copy, /help, /hotkeys, /theme, /settings, /leave, /collab, /exit, /quit).

Known v1 limit for guests: a turn already streaming when you join becomes visible from its next message boundary.

Web client

packages/collab-web is a standalone browser client for the same links — no omp install needed on the guest side. The relay serves it at /, which is what makes the /collab deep link click-to-join: https://<relay>/#<link> loads the client and auto-connects from the fragment. It renders the live transcript (streaming text, thinking, tool cards), a subagent panel with on-demand transcripts, and a composer with the same guest powers (prompt, interrupt, hub actions). Run bun run dev in the package for a local instance, bun run mock-host for an offline scripted host to develop against, and bun run build to emit a static dist/ deployable anywhere (HTTPS required for WebCrypto). The client never talks to anything but the relay, and the key stays in the URL fragment.

Set collab.webUrl when the browser UI is hosted separately from the websocket relay. When empty, /collab derives http(s)://host[:port] from collab.relayUrl; explicit web UI URLs must use https:// except for http://localhost development origins. The generated browser URL still carries the relay-specific collab link in the fragment.

Settings

Setting	Default	Meaning
collab.relayUrl	wss://my.omp.sh	Relay used by /collab when no relay is passed inline
collab.webUrl	empty	Browser UI URL for /collab links; empty derives from relay; explicit http:// is allowed only for localhost
collab.displayName	OS username	Name shown to other participants
share.serverUrl	https://my.omp.sh/s	Share viewer/upload base used by /share (links are <base>/<id>#<key>)
share.redactSecrets	true	Run the secret obfuscator over /share snapshots before upload

Self-hosting the relay

The relay is a small content-blind Go service. It keeps no state beyond live connections and exposes:

• GET / — the static collab-web guest client (target of the /collab deep link),
• GET /r/<roomId>?role=host|guest — WebSocket upgrade,
• POST /s / GET /s/<id> / GET /s/<id>/raw — /share blob upload, viewer page, and blob fetch,
• GET /healthz — liveness.

Architecture notes

Hub topology — the host is authoritative, guests never peer:

1. entry frames — durable session entries, broadcast pre-blob-externalization so images stay inline (guests cannot resolve host blob refs). Guests append them verbatim (ids preserved) to a replica session file under ~/.omp/collab/<roomId>.jsonl and into the agent's message array, which is why /dump and context estimates work.
2. event frames — live agent events, fed straight into the guest's normal event controller; rendering is events-only to prevent double-render.
3. state frames — debounced footer snapshots: streaming flag, the host's full model object and thinking level (applied to the guest's replica agent state, so model display and context-window math are native), host context numbers, and participants.
4. bus frames — mirrored task-subagent lifecycle/progress EventBus traffic, republished on the guest's local bus so the subagent HUD and status-line count work natively.
5. agents frames — agent-registry snapshots feeding a guest-local registry, so the Agent Hub table renders host subagents.

Guest→host: hello, prompt, abort, agent-cmd (hub chat/kill/revive), and fetch-transcript (incremental subagent-transcript reads answered by targeted transcript frames). The replica loads through the regular /resume machinery, so theming, ctrl+o, and transcript behavior are native by construction; the guest process never chdirs to host paths.