Lightweight WebTTY Tunnels

A lightweight WebTTY tunnel is the fastest way to make one machine reachable. It uses the same tunnel inventory and labels as other rstream tunnels, and its lifecycle follows the server process. When the process is online, the terminal can be discovered. When the process stops, the lightweight WebTTY entry disappears.

Use this mode for temporary access, demos, development machines, short-lived agent work, and support sessions that do not need persistent inventory or managed recordings.

This mode is online-only because the tunnel process is the product object while it is connected.

remote machine
  rstream webtty server -v --rstream --name shell
        |
        | outbound tunnel
        v
rstream live tunnel inventory
        |
        | labels mark it as WebTTY
        v
operator CLI, rstream ui, or browser endpoint

Registered servers are covered separately because they add a durable product object, policies, session recordings, live collaboration, and workspace-managed encryption. A lightweight WebTTY tunnel remains tunnel-native by design.

Start a lightweight WebTTY tunnel

Start the server from the machine that exposes the terminal:

rstream webtty server -v --rstream --name shell

This command uses the active rstream project context. If several projects are configured, select the project first:

rstream project use <project-endpoint>

The server publishes a browser-capable WebTTY endpoint by default. The native CLI does not need to copy that browser URL; it can use the stable rstream name:

rstream webtty exec --url rstrm://shell -- whoami
rstream webtty client --url rstrm://shell

The expected behavior is:

rstream webtty list
  shows shell while the process is online
 
rstream webtty exec --url rstrm://shell -- whoami
  runs the command and returns stdout, stderr, exit code, and duration
 
server process exits
  shell disappears from lightweight WebTTY inventory

No registered server object is created. No managed recording history is created.

Keep it private

Use a private lightweight WebTTY tunnel when only native rstream clients may connect:

rstream webtty server -v --rstream --name shell --no-publish

The CLI and rstream ui can still connect through rstrm://shell. Browser sessions need a published WebSocket endpoint, so a private lightweight WebTTY tunnel is intentionally not browser-facing.

private lightweight WebTTY tunnel
        |
        +--> native CLI: yes
        +--> rstream ui: yes
        +--> Dashboard browser terminal: no published endpoint

Add labels

Labels make temporary machines easier to find. Use labels that describe intent rather than implementation details:

rstream webtty server -v \
  --rstream \
  --name edge-lab \
  --label role=codex \
  --label environment=lab \
  --label capability=docker

Then filter from the client side:

rstream webtty list --filter 'labels.rstream.webtty.label.role=codex' -o json

The registered server model also supports durable labels. The ownership is different. Lightweight labels live with the runtime tunnel, while registered server labels live on the persistent server record and can be extended by runtime labels.

Use command execution for agents

Agents, CI jobs, and other automation normally use exec:

rstream webtty exec --url rstrm://edge-lab --output json -- sh -lc 'id && hostname'

exec opens one WebTTY session, runs the command, returns the result, then closes the session. That shape is easier to audit and easier for automation to reason about than a long interactive terminal.

Use client when a human needs a terminal emulator:

rstream webtty client --url rstrm://edge-lab

Filesystem sidecar

The optional filesystem sidecar adds file access next to command execution. It lets clients list directories, read files, upload files, or write files under one configured root without encoding file transfer into shell commands.

rstream webtty server -v --rstream --name shell --fs-root /srv/app --fs-read-only

Access it with WebTTY filesystem commands:

rstream webtty fs ls --url rstrm://shell /
rstream webtty fs read --url rstrm://shell /README.md

The sidecar is not a sandbox. It runs with the WebTTY server process permissions, so expose the narrowest useful directory.

The sidecar is refused when WebTTY end-to-end encryption is active. Terminal E2E protects terminal payloads; the sidecar is a separate file API and must not appear beside an encrypted terminal as if it had the same protection.

Explicit-key E2E

Lightweight tunnels can use explicit-key WebTTY E2E. In that local known-server workflow, the server has a WebTTY endpoint identity, the client accepts that server endpoint identity before sending terminal content, and the server verifies a signed client proof before running commands.

On the server host:

rstream webtty identity create --name shell
rstream webtty identity show --name shell --endpoint-identity

Copy the endpoint identity printed by the second command. On the client host, create a client identity:

rstream webtty identity create --name operator-device
rstream webtty identity show --name operator-device --endpoint-identity

Copy the client endpoint identity printed by the second command to the server host and authorize it once:

rstream webtty authorized-client add operator-device \
  --identity shell \
  --key '<client-endpoint-identity>'

Start the server:

rstream webtty server -v \
  --rstream \
  --name shell \
  --identity shell

On the client host, trust the server endpoint identity once:

rstream webtty known-server add shell \
  --key '<server-endpoint-identity>' \
  --client-identity operator-device
rstream webtty exec --url rstrm://shell -- whoami

The known server endpoint identity is public server material. It verifies the server and encrypts the terminal session key for that server, but it is not a client authorization secret. The optional --client-identity association tells the client which local identity to use when the server asks for a signed client proof. The authorized client entry is public client signing material. It lets the server verify the client's signed proof before starting a process, and it can be added or removed while the server is already running.

If the client has no known key for a lightweight E2E server, it fails before terminal content is sent. rstream ui follows the same rule: it can ask which local identity to use only after the server endpoint identity is already pinned.

Workspace-managed E2E is not a lightweight WebTTY tunnel feature. Use Registered Servers with an Enterprise workspace and Workspace Protection when key custody is managed through trusted browsers, trusted devices, and Recovery Kit recovery.

When to register the server

Move to a registered WebTTY server when the machine becomes a durable product object:

The registered workflow is documented in Registered Servers.