WebTTY

WebTTY gives a remote machine an outbound-only terminal surface for shells, command runners, browser access, and CLI access without exposing an inbound SSH port on the remote network.

The remote machine runs rstream webtty server. Operators connect from the rstream CLI, rstream ui, the Dashboard, or a browser integration. The engine authenticates the caller, applies project policy, routes the WebTTY protocol, and, when the server is registered, can manage session metadata, recordings, live attach, and control transfer.

Mental model

WebTTY has two product shapes. The lightweight WebTTY tunnel path uses the tunnel inventory and labels, and it disappears when the process stops. The registered server path creates a durable project object and lets the engine treat terminal sessions as first-class product sessions.

The first shape is tunnel-native. The live process is the product object, so discovery and labels come from the active tunnel.

Lightweight WebTTY tunnel
 
Operator, browser, CLI, agent
        |
        | rstrm://shell or published WebTTY URL
        v
rstream tunnel inventory + labels
        |
        | live tunnel only
        v
remote rstream webtty server

The second shape adds durable product state. The server record, policy, recording configuration, and session APIs exist even when the runtime process is offline.

Registered WebTTY server
 
Operator, browser, CLI, agent
        |
        | rstrm://prod-shell
        v
registered server record
        |
        | policy, recording, E2E, live session APIs
        v
engine WebTTY protocol router
        |
        | enrolled outbound server connection
        v
remote rstream webtty server

This distinction is the main rule to keep in mind. A lightweight WebTTY tunnel is useful when the tunnel itself is the product object. A registered server is useful when the machine, its policy, its recordings, and its session history remain visible even when the process is offline.

For a registered server, protocol=webtty is admitted by the engine only after the runtime proves possession of the enrolled server identity. Labels describe the runtime, but they are not treated as proof. Managed recordings, live attach, control transfer, and replay all depend on that verified registered-server admission.

Choose the right mode

Use a lightweight WebTTY tunnel when you need a terminal quickly. The server is discovered through tunnel inventory and labels, and it exists only while the tunnel is online. This is the best path for development machines, demos, temporary support, or automation that does not need persistent server inventory or managed recordings.

rstream webtty server -v --rstream --name shell
rstream webtty exec --url rstrm://shell -- whoami

Use a registered WebTTY server when the machine is part of a production access surface. A registered server is a persistent project object with a server id, enrollment file, server identity, labels, recording policy, encryption policy, access policy, and managed session APIs. When the same host creates and runs the server, create and enroll it in one command.

rstream webtty server create prod-shell --enroll
rstream webtty server -v --server-id <server-id>

The registered path is required for managed recordings, live session APIs, stable offline inventory, and workspace-managed end-to-end encryption.

Availability

WebTTY exists across rstream, but not every deployment shape carries the same managed product surface.

Explicit-key E2E is a WebTTY client/server capability and can be used when the client and server are configured with known server endpoint identities and authorized client signing keys. Workspace Protection is an Enterprise workspace capability. Workspace-managed WebTTY E2E depends on that workspace model, so trusted browsers/devices, Recovery Kit, workspace key grants, and trusted runtime-host enrollment replace operator-distributed WebTTY keys.

What WebTTY protects

Every managed rstream connection is authenticated and transport-encrypted. Published tunnel entrypoints can additionally enforce mTLS when the runtime and project policy enable it. Browser-facing HTTP/WebSocket entrypoints can also enforce token authentication, rstream Auth, challenge mode, IP or Geo policy, and project access policy depending on the tunnel shape.

WebTTY can also protect terminal bytes with end-to-end encryption. In that mode, the engine still parses WebTTY protobuf messages, routes session traffic, records metadata, and enforces policy. The terminal payload itself is encrypted before it crosses the engine, so the engine does not see plaintext stdin, stdout, or stderr.

E2E WebTTY also authenticates endpoints. The client verifies the WebTTY server endpoint identity before sending terminal content, and an E2E server verifies a signed client proof before command execution. That keeps encryption from becoming an open channel to any process that can answer the protocol.

There are two key models. Explicit-key encryption is operator-managed and works with local known WebTTY server keys. Workspace-managed encryption uses Workspace Protection, trusted browsers, trusted devices, a Recovery Kit, workspace key grants, and trusted runtime-host enrollment.

Transport encryption
  protects network links.
 
WebTTY E2E
  authenticates WebTTY endpoints and protects terminal stdin/stdout/stderr.
 
Workspace Protection
  protects workspace key material used by trusted browsers/devices.

Those layers are deliberately separate. A session can be transport-encrypted without WebTTY E2E. A workspace can use Workspace Protection without forcing every server to use workspace-managed WebTTY encryption. A client can be authorized by rstream permissions and still fail to decrypt if its browser or device is not trusted.

How sessions are managed

Lightweight WebTTY tunnels do not create managed recordings. They are tunnel sessions with WebTTY labels.

Registered WebTTY servers create managed sessions. A managed session can be listed, inspected, joined as a spectator, exported as a readable text log, or exported as JSON event data depending on the recording policy and permissions. If the session uses WebTTY E2E, recorded terminal payloads stay encrypted in storage and are decrypted by trusted browsers or devices.

Live collaboration is built around one active controller. Spectators can attach to stdout and stderr. A user who needs stdin or resize control requests control, and the request is resolved by the current controller or an authorized owner/admin path.

Live collaboration follows one runtime rule. Output can fan out to several participants, but input and resize are accepted only from the active controller.

remote TTY
   |
   | stdout / stderr
   v
engine live route
   |\
   | \--> spectator
   | \--> spectator
   |
   +---- active controller
          |
          | stdin / resize
          v
        remote TTY

The remote WebTTY server does not decide who is watching or who owns control. It runs the terminal. The engine owns collaboration state and gates input before it reaches the remote process.

Next steps

Start with Quickstart if you want to validate WebTTY on one machine. Move to Registered Servers when the server persists in inventory, records sessions, or uses managed policies. Read End-to-End Encryption before enabling encrypted terminal payloads in production. Use Session Recordings and Live Collaboration to understand managed session behavior.

For agent-facing access, use WebTTY over MCP. It explains why rstream mcp serve is the preferred WebTTY surface and where the restricted hosted MCP fallback fits. For a low-level command catalog, use CLI Reference. For browser integrations and recording replay helpers, use Browser and SDK Usage. For daemon and host-level concerns, use Operations. The WebTTY FAQ collects short answers that do not belong in the main reference flow.