WebTTY Live Collaboration

Live Collaboration

Attach to live WebTTY sessions, request control, and transfer terminal ownership.

Written by uartnet

@uartnet

Live collaboration is available for managed WebTTY sessions. It lets authorized users attach to an active terminal as spectators and, when allowed, request control of stdin and terminal resize.

The WebTTY server on the remote host does not implement collaboration by itself. The engine owns the live routing. It fans out stdout and stderr to attached participants, accepts stdin only from the active controller, and applies control-transfer decisions before terminal input reaches the remote process.

Live collaboration uses two related surfaces. Terminal bytes stay on WebTTY protocol connections; discovery, requests, approvals, and UI synchronization use the HTTP control API.

WebTTY protocol connection
  carries terminal frames over plain, WebSocket, or WebTransport
        |
        v
engine live router
  fans out output, gates input, applies controller state
        |
        +--> spectator WebTTY connection
        +--> controller WebTTY connection
 
HTTP control API
  lists sessions, creates control requests, resolves requests,
  and streams control-plane events to dashboards, TUIs, or agents

The attach path still uses WebTTY protocol connections for terminal bytes. The HTTP API is the control plane around those connections, covering discovery, request state, permissions, approval, and UI synchronization.

List active sessions

Start by listing active managed sessions:

rstream webtty sessions list --status active

The session list shows registered server metadata, user metadata, origin, status, and session ids. Non-interactive sessions can appear here too, but they often close before a human can attach.

Attach as a spectator

Join a live session without control:

rstream webtty sessions join <session-id>

This attaches to output. A spectator can see stdout and stderr but does not send stdin and does not resize the remote TTY. This is the safest mode for incident review, peer assistance, and supervised operations.

Use terminal mode when the local client renders terminal control sequences interactively:

rstream webtty sessions join <session-id> --tty

Request control

When you need to type into the remote terminal, request control:

rstream webtty sessions join <session-id> \
  --tty \
  --interactive \
  --request-control \
  --reason "Need to apply the rollback"

The request is visible to the active controller and to authorized owners/admins according to policy. The requesting client remains attached while waiting for the decision so it can receive the control event.

Control can also be requested after attaching:

rstream webtty sessions request-control <session-id> \
  --participant-id <participant-id> \
  --reason "Need to inspect the failing process"

Resolve a control request

List pending requests:

rstream webtty sessions control-requests <session-id>

Grant or refuse a request:

rstream webtty sessions resolve-control <session-id> <request-id> --action grant
rstream webtty sessions resolve-control <session-id> <request-id> --action refuse

Use revoke when control must be taken away from a participant:

rstream webtty sessions resolve-control <session-id> <request-id> --action revoke

When the current controller is resolving a request, the controller participant id can be supplied:

rstream webtty sessions resolve-control <session-id> <request-id> \
  --approver-participant-id <participant-id> \
  --action grant

Owners and admins may resolve through a permission-based path where policy allows it.

Follow session events

Live collaboration is evented. Clients subscribe to session events when they need immediate UI updates after a participant joins, a request is created, a request is granted or refused, or controller ownership changes.

rstream webtty sessions events <session-id>

Use events instead of polling when building a browser UI, TUI, or automation that needs accurate live state.

Treat the event stream as the source of truth for transient UI state:

Event kind	Typical UI reaction
Participant joined	Add a spectator or controller to the connected-user list.
Participant left	Remove the participant and clear stale waiting states.
Control request created	Notify the active controller and authorized owners/admins.
Control request granted	Switch the active controller and allow stdin/resize from that participant.
Control request refused	Keep the requester attached as a spectator and show the refusal.
Controller revoked	Stop accepting stdin/resize from the previous controller.

Terminal size

Only the active controller drives remote terminal size. Spectators render output locally, but their resize events do not change the remote TTY.

After control transfers, the new controller becomes responsible for resize. The remote size changes when the new controller sends the next resize event. This avoids multiple viewers racing over terminal dimensions.

Non-interactive sessions

Non-interactive sessions are usually created by agents, scripts, CI jobs, or scheduled automation. They can be listed, recorded, and exported, but control transfer is rarely useful because the command has a bounded lifecycle and stdin is often closed.

Use session group metadata to correlate repeated non-interactive commands from the same workflow. Treat live attach/control as primarily useful for long-running interactive sessions.

Product permissions

The product permission model remains simple. Read-only session access can view live sessions as a spectator. Read-write session access can create sessions and request control. Owners and admins can resolve control requests when workspace policy allows it.

The backend can enforce finer internal checks, but users do not need to understand a long list of internal permission bits to know whether they can watch, request control, or administer a session.

Session Recordings WebTTY over MCP