WebTTY

rstream WebTTY is the remote terminal protocol built for rstream tunnels and is available on Basic, Pro, Enterprise, and self-hosted deployments. It is intended for cases where a remote terminal must be reachable from the CLI, from the rstream Dashboard, or from a browser-based integration without depending on a conventional inbound service such as SSH.

A WebTTY server runs on the remote machine and establishes the outbound connection to the rstream edge network. The operator side can then connect through the native rstrm:// dialer, through the Dashboard, or through a published wss:// endpoint when the session is opened from a browser-based client. The protocol is built on web transports and fits naturally into the rstream tunnel model while still covering the core terminal workflows usually associated with SSH. The full operational path, including automation and a comparison with SSH, is covered in Access Remote Machines with rstream WebTTY.

Security model

WebTTY access is always mediated by the rstream edge network. In the native CLI workflow, access is granted through the authenticated rstream client context that dials the tunnel. In the published browser workflow, access is granted through a short-lived token bound to the published session. In both cases, the edge verifies the caller before the session reaches the remote machine.

This distinction matters because a published WebTTY server is not equivalent to a published TCP service such as SSH. Publication creates a browser-capable wss:// entrypoint on the edge, but it does not make the remote terminal openly reachable without authentication. The private form removes that browser entrypoint entirely and keeps the server on the native rstream path only.

The execution model is also straightforward. rstream webtty server is the long-running server process and the terminal sessions run in that process context. By default, commands execute as the operating-system user that launched the server. The client can request a different target user, working directory, or environment when that is part of the operational contract of the machine and permitted by the host.

Server modes

The local validation form listens on a regular WebSocket address and does not create a tunnel:

rstream webtty server --listen 127.0.0.1:8080
rstream webtty client --url ws://127.0.0.1:8080

When started with --rstream, the server is exposed through an rstream tunnel. The default form is published and is the one used by the Dashboard:

rstream webtty server --rstream -v --name homelab-macmini

This published form creates the HTTP tunnel shape required by browser sessions and attaches the standard WebTTY labels. It is the form used by the Dashboard and by custom browser-based clients.

The same server can also stay private:

rstream webtty server --rstream -v --name homelab-macmini --no-publish

In private mode there is no published browser entrypoint. The server remains reachable through the native rstream dialer, which keeps the CLI workflow unchanged while removing the public surface entirely.

Discovery and operator workflows

The dedicated inventory command for WebTTY servers is:

rstream webtty list

This command only returns the WebTTY servers that are currently online. It is the simplest discovery surface for operators and for scripts. Structured output is available through -o json, and the quiet form -q returns only the native dial targets.

rstream webtty list -o json
rstream webtty list -q

For a live operator console across WebTTY servers, tunnels, and clients, use:

rstream ui

rstream ui subscribes to the signaling API and keeps the inventory current without a manual refresh cycle. From the WebTTY view, pressing Enter opens the selected server directly inside the UI. This is the operator-facing workflow when inventory, inspection, and connection happen in the same terminal session.

When lower-level tunnel properties or label-level filtering are required, the raw tunnel inventory remains available:

rstream tunnel list --filter 'labels.application-protocol=rstream.webtty'

The Dashboard relies on that same tunnel surface to identify published WebTTY servers and open the browser session.

Native CLI connections

The WebTTY client accepts ws://, wss://, and rstrm:// URLs. For an rstream-backed server, the native CLI path is usually the most direct:

rstream webtty client --url rstrm://homelab-macmini -- printf 'hello world\n'
rstream webtty client --url rstrm://homelab-macmini

The first form runs a command and returns. The second opens an interactive terminal. The same syntax works whether the server is published or private because the CLI dials the tunnel through the local rstream configuration rather than through the published host.

Published browser and WSS access

When a WebTTY server is published, two browser-facing paths become possible. The first is the rstream Dashboard, which resolves the published endpoint, obtains the required token, and opens the terminal session in the browser. The second is a browser-based integration built outside the Dashboard, using the published wss:// endpoint and a compatible WebTTY client.

That same transport can also be used directly from the CLI when a URL-based flow is required.

The published host can be resolved from tunnel inventory:

rstream tunnel list --filter 'name=homelab-macmini,labels.application-protocol=rstream.webtty' -o json

The direct wss:// form then becomes:

rstream webtty client --url 'wss://<published-host>?rstream.token=<token>'

Published WebTTY always requires that token on the direct wss:// path. The Dashboard obtains a short-lived token from the control plane API and injects it before opening the browser session. Direct CLI or SDK use of the published endpoint requires the same token to be supplied explicitly. The CLI and SDK token workflow is documented separately in Tokens and CLI Workflow.

Advanced session controls

The client exposes the main session controls that usually matter in terminal operations. --interactive and --no-interactive force the execution mode explicitly. --tty and --no-tty do the same for TTY allocation. These controls are most useful when WebTTY is embedded into a broader operational toolchain and the session mode must remain predictable.

The remote process can also be shaped through environment variables, a working directory, and a target user:

rstream webtty client \
  --url rstrm://homelab-macmini \
  -e APP_ENV=prod \
  -e TERM=xterm-256color \
  -w /srv/app \
  -u admin \
  -- sh -lc 'printf "%s|%s|%s\n" "$PWD" "$APP_ENV" "$(id -un)"'

On the server side, the operational flags are centered on exposure and process lifecycle. --listen keeps the server local. --rstream exposes it through a tunnel. --name, --publish, and --no-publish define how that tunnel is addressed and whether a browser-facing entrypoint exists. --retry, --retry-interval, and --shutdown-timeout control reconnect and shutdown behavior for long-running processes.