Session Recordings

Session recordings are available for registered WebTTY servers with recording enabled. Lightweight WebTTY tunnels do not create managed recordings; they are live tunnel sessions only.

A managed recording is stored as an ordered event stream. Events can include stream direction, timestamps, terminal resize metadata, terminal mode metadata, plaintext payloads for non-E2E sessions, or encrypted payloads plus crypto metadata for E2E sessions.

A managed recording follows the terminal event path below. The engine records ordered terminal events; export tools later turn those events into a readable text log or a JSON event file.

remote TTY session
        |
        | stdin, stdout, stderr, resize, terminal mode
        v
engine WebTTY recorder
        |
        | ordered event stream
        v
recording storage
        |
        | text export or JSON event export
        v
operator, auditor, UI, SDK integration

The recording is not a screen recording. It is a terminal event log. That keeps export useful for audit and automation while preserving enough metadata for later replay tooling.

List sessions

List recent sessions in the active project:

rstream webtty sessions list

Filter by registered server, status, origin, or time window when the project has many sessions:

rstream webtty sessions list --server-id <server-id>
rstream webtty sessions list --status active
rstream webtty sessions list --origin codex
rstream webtty sessions list --started-from 2026-06-10T08:00:00Z
rstream webtty sessions list --started-to 2026-06-10T18:00:00Z

origin is client-provided metadata. Use it to distinguish human sessions from API, automation, CI, scheduled jobs, or agent workflows.

Inspect one session

Show metadata for one session:

rstream webtty sessions show <session-id>

The session metadata includes the registered server id, tunnel id, session group id, initiating user, origin, status, timestamps, terminal size, recording policy, encryption policy, and recording availability.

For non-interactive automation, session group metadata is important. A human may keep one terminal open for a long time. An agent or CI workflow may create many short sessions, and the group id is the way to correlate them as one workflow.

Session groups make short-lived agent work understandable. Many short commands can still belong to one operator or agent workflow.

human workflow
  one long interactive session
  one session group
 
agent workflow
  many short exec sessions
  one shared session group when the caller provides workflow context

Export a readable text log

The default operator export is a text log:

rstream webtty sessions export <session-id> --format text --file session.log

Text export is designed to behave like terminal scrollback. It includes stdout and stderr by default and omits stdin by default. Include stdin only when the audit workflow needs to show what was typed or sent by automation:

rstream webtty sessions export <session-id> \
  --format text \
  --include-stdin \
  --include-timestamps \
  --file session.log

Resize and terminal mode markers are optional:

rstream webtty sessions export <session-id> \
  --format text \
  --include-resize-markers \
  --terminal-mode-markers \
  --file session.log

Alternate-screen applications

Applications such as htop, vim, less, and many full-screen TUIs use the terminal alternate screen. Text export follows the same principle as saving terminal scrollback from a desktop terminal.

If the application exits and restores the main screen before export, its transient screen is not rendered into the text log. If export happens while the alternate screen is active, the active alternate-screen snapshot can be included.

This behavior matches a normal terminal save operation. Closed alternate-screen content is not treated as scrollback; an active alternate screen can be captured because it is still the visible terminal state.

main screen scrollback
        |
        | open htop / vim / less
        v
alternate screen
        |
        | exit app and restore main screen
        v
main screen scrollback
 
Text export after exit:
  exports the main screen scrollback, not the closed alternate screen.
 
Text export while app is still active:
  may include the active alternate-screen snapshot.

The default is to include the active alternate-screen snapshot when the session is still in alternate screen:

rstream webtty sessions export <session-id> \
  --format text \
  --active-alternate-screen \
  --file session.log

Disable that behavior when the export must contain only main-screen scrollback:

rstream webtty sessions export <session-id> \
  --format text \
  --active-alternate-screen=false \
  --file session.log

Export JSON event data

Use the JSON format when the recording needs to be preserved for replay tooling, forensic analysis, or future reprocessing:

rstream webtty sessions export <session-id> --format json --file session.json

The JSON format preserves event order, sequence cursors, stream direction, terminal resize events, terminal mode metadata, crypto metadata, and payload data in the stored representation. It is less readable than text export, but it retains more information.

Encrypted recordings

When the session used WebTTY E2E, stored terminal payloads remain encrypted. Listing sessions and reading metadata does not decrypt terminal content. Decryption requires both authorization and trusted local key material.

From the CLI, export uses the local trusted device or explicit-key material available to the caller. From browser UI, decryption happens in a trusted browser. A trusted workspace device is eligible to decrypt workspace-managed recordings, but a given encrypted session still needs a session key grant for that browser or device. In normal use, that grant is created for the browser or device that opened or joined the session.

External integrations use the JS SDK helpers instead of reimplementing replay crypto:

import { createWebTTYE2EReplayPayloadCryptoFromKeyGrant } from "@rstreamlabs/webtty";
import { decryptWebTTYRecordedTextLog } from "@rstreamlabs/webtty";
import { renderWebTTYRecordedTextLog } from "@rstreamlabs/webtty";

Use renderWebTTYRecordedTextLog for plaintext recordings. Use createWebTTYE2EReplayPayloadCryptoFromKeyGrant with decryptWebTTYRecordedTextLog for encrypted recordings after retrieving authorized decrypt material.

Decryption stays on the trusted client. The server returns authorized encrypted material, and trusted clients use the JS SDK locally to render readable output.

encrypted recording events
        |
        | authorized decrypt-material API
        v
trusted browser or trusted device
        |
        | JS SDK decrypts locally
        v
readable text log or decrypted JSON event stream

Retention

Retention depends on the project plan and server policy. Short retention is useful for operational debugging. Longer retention is intended for audit, incident review, and regulated environments.

Deleting or rotating a WebTTY server does not automatically remove historical recordings unless the retention or deletion policy says so. Treat server lifecycle and recording lifecycle as separate operational decisions.