Operations

WebTTY servers are remote access processes. Treat production servers like other privileged service processes by choosing the operating-system account deliberately, keeping configuration reviewable, locking down private key files, and making startup and shutdown observable.

Service ownership

For lightweight WebTTY, starting the server from a user session is often enough. The server inherits that user's environment and permissions, and spawn execution mode runs commands as children of that process.

For registered servers, prefer a service account and a runtime config file. The service manager command stays stable while the config file carries WebTTY runtime settings:

rstream webtty server -v --webtty-config /etc/rstream/webtty/prod-shell.yaml

That separation keeps the service definition boring. The service manager starts one stable command, the runtime config describes WebTTY behavior, and private material stays in dedicated enrollment and identity files.

service manager
  ExecStart=rstream webtty server -v --webtty-config /etc/rstream/webtty/prod-shell.yaml
        |
        v
WebTTY runtime config
  registered server reference, transport, execution mode, labels
        |
        v
local enrollment and identity files
  private material, strict local permissions

On Linux, run the process under systemd. On macOS, use a LaunchAgent when the server belongs to a user session, or a LaunchDaemon when the machine-level service model is intentional. On Windows, use a service wrapper or scheduled task under the account that owns the rstream configuration and local WebTTY files.

Configuration surfaces

WebTTY has three local configuration surfaces. Keep them separate.

The runtime config may reference server.serverId when the default rstream home is correct, or server.serverEnrollment when a service account uses explicit file locations. Avoid copying private keys into general-purpose YAML files. Use host permissions or the host secret manager for identity material.

Login mode

Registered servers default to login execution mode. This is the mode for a managed shell service rather than a child process of an already-authenticated desktop user.

rstream webtty server -v --server-id <server-id> --execution-mode login

If the server always uses a specific operating-system user, configure it explicitly:

rstream webtty server -v --server-id <server-id> --execution-mode login --login-user deploy

Allowing clients to request an operating-system user is a stronger host policy decision:

rstream webtty server -v --server-id <server-id> --execution-mode login --allow-client-user

Only enable it when the host login path and local authorization rules are ready for that behavior.

File permissions

Identity files contain private keys. Enrollment files contain server enrollment material. Keep both readable only by the account that runs WebTTY.

A production layout can separate runtime config from key material:

/etc/rstream/webtty/prod-shell.yaml
/etc/rstream/webtty/prod-shell.enrollment.yaml
/var/lib/rstream/webtty/identities/prod-shell.identity.json

When the organization already uses a host secret manager, store or mount private material through that system instead of making it part of a general-purpose config file.

Process logs

Process logs make operational behavior observable without leaking terminal data. At startup, log the selected transport, execution mode, encryption state, filesystem-sidecar state, registered-server resolution, labels, and retry behavior. At shutdown, log whether the process stopped cleanly or because of an error.

Process logs must not include terminal payloads, private keys, local enrollment files, wrapped payload keys, or decrypt material. Managed session recordings are separate from process logs and are controlled by the registered server recording policy.

Online state

Registered server online state is derived from the associated live runtime tunnel and engine state. There is no separate WebTTY liveness object to configure or troubleshoot.

If a registered server is offline, it remains visible as a registered object. Operators can still see the server record, inspect policy, and access past recordings according to retention and permissions.

Protocol parsing

Managed WebTTY features require the engine to parse the WebTTY protocol. That parsing is what enables managed sessions, recordings, live attach, control transfer, and E2E routing where protocol metadata is visible but terminal payloads can remain encrypted.

Lightweight WebTTY over HTTP and labels remains useful for simple tunnel use. It is the right choice for temporary servers and demos that do not need persistent inventory, managed session logs, or live collaboration.

Filesystem sidecar

The filesystem sidecar adds file access next to command execution. It can list, read, upload, download, and write files under one configured root. Production deployments enable it only for the narrowest useful directory:

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

The sidecar resolves paths under the configured root, but it is not a sandbox. Run WebTTY as a dedicated user and expose only the directory tree the workflow needs.

The sidecar is refused when WebTTY E2E is active. If terminal payloads require end-to-end encryption, do not expose a separate file surface that is not protected by the same model.

Failure behavior

Production WebTTY fails visibly when trust cannot be established. If --e2e is set and the resolved server is not E2E, the client fails. If a workspace-managed server key is not trusted, clients fail before sending terminal content. If a trusted workspace device is required and missing, clients fail during resolution. Unsupported crypto suites fail closed.

These failures are intentional. Remote shell tooling must not silently downgrade security because a local key file is missing, a server key changed, or a workspace device was not enrolled.