WebTTY Quickstart

This quickstart validates the lightweight WebTTY path. It starts one WebTTY server, discovers it through rstream, then connects from the CLI. Use it before setting up registered servers, recordings, live collaboration, or workspace-managed encryption.

You need the rstream CLI installed and logged in. The machine that starts the server and the machine that connects to it must resolve to the same project, either through the active CLI context or explicit project configuration.

rstream login
rstream project list

If you are testing on a new workstation, run rstream project use <project-endpoint> first so both server and client commands use the same project.

This page intentionally starts with the smallest working shape:

remote machine
  rstream webtty server
        |
        | outbound rstream tunnel
        v
rstream project inventory
        |
        | rstrm://shell
        v
operator CLI or browser

At the end of the quickstart, the server process has connected outbound, the project can discover the server, and a client can open a terminal session without any inbound port on the remote machine.

Validate locally first

Start with a local server when you only want to check the WebTTY protocol and client behavior. This does not create an rstream tunnel.

rstream webtty server -v --listen 127.0.0.1:8080 --allow-unauthenticated

In another terminal, run one command through that server:

rstream webtty exec --url ws://127.0.0.1:8080 -- whoami

webtty exec is the automation shape. It opens a WebTTY connection, runs the command, returns stdout, stderr, exit code, and duration, then closes the session. For a human terminal, use the interactive client:

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

Close the local server with Ctrl-C when the validation is complete.

Publish through rstream

Start the same server through an outbound rstream tunnel:

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

The remote machine initiates the connection to rstream. It does not need a public IP address or inbound firewall rule.

From another terminal or another machine with access to the same project, list online WebTTY servers:

rstream webtty list

Then connect through the native rstream URL:

rstream webtty exec --url rstrm://shell -- uname -a
rstream webtty client --url rstrm://shell

The rstrm://shell URL resolves through the rstream context. It is usually the simplest CLI target because it does not require copying a published browser hostname or short-lived browser token.

The expected result is:

rstream webtty list
  shows the online server named shell
 
rstream webtty exec --url rstrm://shell -- uname -a
  returns stdout, stderr, exit code, and duration

Keep it private

If the terminal must not have a browser-facing endpoint, keep the tunnel private:

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

The CLI can still reach it through rstrm://shell. Browser sessions need a published endpoint, so a private WebTTY tunnel is CLI-only.

Run commands for automation

Automation and agents normally use exec, not an interactive terminal:

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

exec defaults to JSON output because callers usually need a structured result. Use client for an operator terminal emulator.

Pass environment, working directory, or a requested user only when the server policy allows it:

rstream webtty exec \
  --url rstrm://shell \
  -e APP_ENV=prod \
  -w /srv/app \
  -u deploy \
  -- sh -lc 'pwd && id && printenv APP_ENV'

Add a filesystem sidecar

The filesystem sidecar exposes a WebDAV view next to the terminal endpoint. It is useful for agents that need to read or write files without encoding file transfer into shell commands.

rstream webtty server -v --rstream --name shell --fs-root "$HOME/project"

Use the WebTTY filesystem commands with paths relative to the configured root:

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

For inspection-only workflows, start the sidecar read-only:

rstream webtty server -v --rstream --name shell --fs-root "$HOME/project" --fs-read-only

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

When to move to registered servers

The lightweight path is intentionally simple. It is the right starting point for temporary servers and quick validation.

Move to a registered WebTTY server when the machine must remain visible while offline, when sessions must be recorded, when live attach/control is required, or when terminal encryption is managed by Workspace Protection.

rstream webtty server create prod-shell --enroll

The registered-server workflow is covered in Registered Servers.

Use this decision table when choosing the next page: