Oko
Oko/Docs

Command reference

oko sessions publish

Offers one session through a WebSocket relay as its publisher and lists it for the organization's members for exactly as long.

Invocation#

Command
oko sessions publish ID --relay URL [--socket PATH]

Inputs and options#

  • ID is the session; --socket names the broker that holds it (the installed one when left out).
  • --relay is the relay's WebSocket URL; the publisher credential is read only from Skarbiec.

Output and state effect#

  • Inserts this member's row in oko_live_sessions (owner, organization, ssh_url oko-relay://session/<ID>?relay=<URL>, the session's directory, its executable's name and attach socket) once the relay and the session are connected, and names it on stderr. The row is renewed before its own declared expiry for as long as the publisher runs; a renewal the registry refuses is named on stderr and tried again. When the relay or the session closes, the row's ended_at is set and the ended row is printed; a row someone else ended is not renewed, and the publisher stops. Oko iOS's Terminals list shows the row and attaches to it as a viewer.
  • Oko Desktop's Sessions screen offers Share on a running, unshared session: its sheet takes the relay address and the Oko service publishes through the native API's sessions publish {id, relay}, running the same publisher inside the service until Stop sharing or the relay closes.

Refusals and safe exits#

  • A missing ID refuses with “oko sessions publish requires <id>” and a missing --relay with “oko sessions publish requires --relay <text>” (exit 2); an invalid relay URL and “the broker at <socket> holds no session <id>; it holds: <ids>” are refused before the relay credential is read; --token, an unavailable oko-pty-relay credential, a member who is not signed in (“the publication cannot be listed for the organization: …”) and bridge failures exit unsuccessfully.
  • Text controls must be the declared input, viewer-attached or resize message. Input requires text; resize requires positive u16 columns and rows. Malformed controls report the broker session and actual parser cause. Input-write, repaint and resize failures propagate through the publisher instead of being discarded; a failed group notification is not replaced with a signal to its leader.
  • If both the bridge and publication cleanup fail, the refusal preserves both causes and the session identity. A renewal-thread panic retains its string payload, or identifies a non-string payload by its actual type; it does not replace an already observed bridge failure. A session's output (publishing) or this terminal's input (viewing) that can no longer be read, or that the relay no longer takes, ends its forwarding with `oko: <what> could not be read and is no longer relayed: <cause>` or `oko: <what> could not be sent to the relay and is no longer relayed: <cause>` on stderr.
  • Invalid UTF-8 in a relay text message refuses with the decoder's actual byte-position cause before control parsing. The client does not replace malformed bytes with replacement characters or allocate a second successful text copy.
  • When the relay closes after sending only part of a WebSocket frame, the client reports the actual received and required byte counts instead of treating that partial header or payload as clean stream closure.

CLI reference#