Browser and SDK Usage

Browser WebTTY integrations use the JS SDK. This is the same surface used by the product terminal and by custom web applications that need to open a WebTTY session from a browser.

A browser does not hold durable rstream credentials. The backend resolves the selected server, checks permissions, mints a short-lived token or session grant, and returns only the connection information needed by that browser session.

Browser integrations keep authorization and rendering separate. The backend resolves and authorizes; the browser renders the terminal and performs local crypto when needed.

browser UI
   |
   | asks application backend for a WebTTY session
   v
application backend
   |
   | checks rstream permissions and resolves server
   v
rstream Control plane / engine
   |
   | short-lived connection envelope
   v
browser WebTTY client

Keep this split even for custom integrations. The browser renders the terminal and performs local crypto when needed. The backend owns authorization, server resolution, token minting, and policy checks.

Open a browser terminal

For a published WebTTY endpoint, the browser client connects over WebSocket with a short-lived token:

import { WebTTY } from "@rstreamlabs/webtty";
 
const terminal = new WebTTY({
  url: "wss://example.rstream.dev/webtty?rstream.token=<token>",
});
 
terminal.connect();

Use short-lived tokens scoped to the selected tunnel or registered server. Do not put personal access tokens, application secrets, or long-lived credentials in browser URLs.

Resolve registered servers server-side

For registered servers, the backend resolves the server and enforces product policy before the browser receives connection data. The browser does not need to know whether the backing server is a lightweight WebTTY tunnel, a registered server, or a workspace-managed E2E server. It receives a session-specific connection envelope.

When the server requires E2E, the browser must also be a trusted workspace browser or receive explicit-key material through an application-specific trust flow. Otherwise the session fails before terminal content is sent.

WebTTY E2E helpers

The SDK exposes payload crypto primitives for integrations that own the trust decision directly:

import { createWebTTYE2EClientPayloadCrypto } from "@rstreamlabs/webtty";
import { generateWebTTYE2EIdentity } from "@rstreamlabs/webtty";

Use explicit-key crypto when the integration owns recipient selection. Use workspace-managed crypto when the browser is a trusted workspace browser and the registered server has a workspace-managed encryption policy.

Do not reimplement key id derivation, HPKE key wrapping, or AES-GCM payload encryption in application code. Use the SDK helpers so browser clients, CLI clients, and recording replay use the same crypto behavior.

Recording replay

The JS SDK also exposes text rendering and encrypted recording replay helpers:

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

Use renderWebTTYRecordedTextLog for plaintext recordings. Use createWebTTYE2EReplayPayloadCryptoFromKeyGrant and decryptWebTTYRecordedTextLog for encrypted recordings after the backend returns authorized decrypt material and the browser has the matching trusted private key.

The replay helpers intentionally implement terminal-scrollback behavior. Alternate-screen applications are excluded from text export after they exit and restore the main screen, while the active alternate-screen snapshot can be included if export happens during the alternate-screen state.

Filesystem sidecar

The filesystem sidecar is a separate file API next to the terminal. It can expose directory listing, file read, upload, download, and write operations under a configured root, and it is separate from terminal payload encryption. Browser integrations do not expose the sidecar when the WebTTY session requires E2E terminal content.

If a browser workflow needs file access next to an encrypted terminal, design that file surface with its own explicit authorization and encryption model. Do not rely on WebTTY terminal E2E to protect a separate WebDAV path.

Transport compatibility

Browser SDK integrations use runtime capability metadata instead of assuming one transport everywhere. WebSocket is the browser-compatible default. WebTransport support is available through the Go runtime where configured. C++ WebTTY utilities support plain and websocket.