CLI Workflow

The rstream CLI can operate in two main modes.

The first mode is interactive and account-wide: authenticate with rstream login, then select a project and open tunnels. This mode is convenient on developer machines because it keeps the local configuration small and makes it easy to switch between projects. Local agent runtimes can initiate the same OAuth device flow through rstream_auth_start and rstream_auth_poll after rstream codex setup; the token is stored in the CLI config and is not returned to the agent prompt. The local MCP login uses the default CLI setup permissions unless an agent explicitly requests broader permissions for a user-approved task such as project creation.

The second mode is project-scoped: create or use a context that already contains an engine endpoint and a token scoped to a single project. This mode is a better fit for servers, CI, and devices because it avoids account-wide credentials and makes the runtime configuration explicit and auditable.

Projects and contexts

A project groups tunnels, credentials, and access controls in the hosted platform. The CLI selects a project by writing a local context that contains the project endpoint and the associated engine endpoint.

A context is a local configuration entry that defines how the CLI connects to rstream. In practice a context contains a name, an API URL, a project endpoint, an engine address, authentication storage, and optional transport settings such as DNS override, local bind configuration, QUIC transport selection, or proxy settings. Contexts can be selected explicitly with --context or set as the default context.

Control plane API and Engine API

In the hosted platform, the Dashboard and Control plane API manage projects and credentials, and resolve a project endpoint into an engine endpoint.

The Engine API is the runtime entrypoint. It hosts tunnel endpoints, enforces access policies, authenticates inbound requests, and relays traffic to upstream services. In self-hosted deployments, the workflow typically targets the engine directly and does not rely on the hosted Control plane API.

Running without login or config files

The CLI can run without a prior login and without pre-existing contexts when the engine endpoint and token are provided through environment variables.

RSTREAM_ENGINE="<project-endpoint>.<cluster-host>:443" \
RSTREAM_AUTHENTICATION_TOKEN="<token>" \
rstream forward 8080

This pattern is useful for containers, CI jobs, and single-purpose agents. If several commands need to share the same target project, a named context is usually easier to inspect and rotate.

Codex and local MCP

rstream codex setup registers a local MCP server that runs rstream mcp serve through the current CLI context. That server can inspect runtime status, list workspaces and projects, start the user-approved OAuth flow, prepare or repair the selected project context, create managed local tunnels, operate WebTTY machines, use the optional WebDAV filesystem sidecar, and expose services that only listen on a remote WebTTY host.

Codex should call rstream_runtime_status first when the local state is unknown. If a login token is missing, the next step is rstream_auth_start followed by rstream_auth_poll. If a login token exists but no usable project context exists, Codex should list the available tunnel projects. With exactly one project, it can prepare that project. With several projects, it should not infer from naming conventions alone or add a preferred example; it should ask the user or use the project explicitly named in the prompt. rstream_runtime_prepare then prepares the chosen project by name, endpoint, or ID, using the stored developer-machine login token without calling /api/tokens.

The remote exposure path is useful when Codex needs complete access to a remote machine: command execution through WebTTY, filesystem access through the sidecar, and network access to a remote-local service through rstream_remote_expose. When that remote-local service is an MCP server, mcp_path labels the tunnel so Codex can discover and call it with the remote MCP tools.

Readiness checks

Run rstream doctor -o json after setup changes or when troubleshooting. It checks the selected config, context, token claims, Control plane API authentication, project resolution, engine address, DNS, TLS or QUIC transport, and live engine inventory. The command is designed for agents and CI because it returns structured status without printing secrets.

Token handling and operational safety

An authentication token is a private secret. If a token is leaked, it should be treated as a credential compromise and revoked or rotated as soon as possible.

In the hosted platform, tokens and application credentials can be revoked from the Dashboard. Developer workstations usually use the long-lived login token stored by rstream login. Remote machines, CI, and devices usually use project-scoped credentials with restricted permissions and resources.tunnels boundaries; scoped does not mean short-lived. Short-lived delegated tokens are for immediate handoff flows such as protected browser URLs, query-token APIs, published MCP sessions, and one-shot startup commands that immediately launch a long-running process.