Codex

rstream gives Codex a controlled way to reach local services, remote machines, device-local MCP servers, and private tunnels without opening inbound ports. The usual shape is intentionally small: the operator keeps a normal rstream CLI context, rstream codex setup registers local MCP tools, and remote devices opt in through WebTTY or their own SDK/runtime process.

That keeps authority where it belongs. Codex does not need a raw project token pasted into a prompt, and operations still go through the same rstream context, permissions, token storage, tunnel policies, and diagnostics used by the CLI.

Configure Codex

Start with a current CLI. Use rstream CLI 1.19.0 or later for runtime preparation, local tunnel lifecycle tools, WebTTY filesystem access, remote exposure, and remote MCP calls.

rstream --version
rstream doctor -o json

On an already configured workstation, register the local MCP server:

rstream codex setup

The generated Codex entry runs:

rstream mcp serve

When RSTREAM_CONFIG is set during setup, the generated MCP entry preserves that config path. This is useful for isolated Codex workspaces, CI-style test homes, or operators who keep multiple rstream configs.

For a clean workstation, it is also valid to run rstream codex setup before login and let Codex initiate the browser approval flow:

Prepare rstream for this Codex session. If login is missing, start the browser approval flow, wait for approval, then prepare the selected project context without minting a delegated token.

Codex should then call rstream_auth_start, show the returned approval URL, and call rstream_auth_poll with wait=true. A separate user code is displayed only when the OAuth provider cannot embed it in the URL. The approved token is written to the local CLI config and is not returned through MCP.

Local and Hosted MCP

rstream exposes two MCP surfaces, and they serve different jobs.

Local MCP is the right default for Codex desktop workflows because it can operate through the user's private rstream dialer and cleanup registry. Hosted MCP is useful for control-plane automation when the caller already has an explicit bearer token.

Project Setup

Codex should prepare a hosted project context with the workstation login credential, not by minting a short-lived token for itself.

Use the Production rstream tunnel project for this session. Check runtime status first, then prepare or repair the local context and report the selected endpoint.

If several projects are available and the user did not name one, Codex should list the choices and ask for the project name, endpoint, or ID. It should not infer from naming conventions or add a preferred example.

Project creation is explicit. Codex should first inspect creation options, show the returned billing impact and next server-selected billing action, and only create or start checkout after the user has approved that action.

Create a new rstream project named Codex Demo Test. First show the available creation option, billing impact, provider, region, and plan. If creation is non-billable, create it, verify it exists, then stop.

For plan-gated features, Codex should inspect the selected plan before acting. Basic projects remain useful for published HTTPS/WebSocket tunnels, WebTTY, token-protected access, and fine-grained tokens. If a requested feature is unavailable, Codex should explain the exact limitation and suggest the closest compatible path before proposing a plan change.

Self-Hosted Engine CE

Codex can help deploy and validate a self-hosted Engine CE instance, but the deployment procedure belongs in Self-Hosted Engine. This page only defines the Codex boundary: CE is a direct-engine runtime, not the hosted Control plane, so Codex should not use hosted workspaces, projects, billing, hosted logs, browser rstream Auth, managed policies, managed credentials, or managed TURN as if they existed.

A good prompt points Codex to the dedicated docs and asks it to keep the edition boundary explicit:

I want to set up a self-hosted rstream Engine CE demo. Read the self-hosted deployment, configuration, and operations docs. Prepare the Docker Compose shape, TLS certificate requirements, JWT generation approach, direct-engine agent context, validation tunnel, Engine API checks, metrics check, and cleanup steps. Do not use hosted project, billing, rstream Auth, managed policy, or Control plane tools for CE.

Codex should read the self-hosted feature boundary before acting. CE uses a direct engine host, static TLS, locally signed JWTs, direct engine contexts or environment variables, Engine API state, Prometheus metrics, and the tunnel modes documented for CE. Hosted-only access features should be treated as unavailable unless the deployment is a private managed runtime that explicitly provides them.

For CLI-created validation tunnels, cleanup follows the process that owns the tunnel. A foreground rstream forward is stopped by stopping that process or its supervisor. Codex should use documented tunnel-management commands for inspection and should not invent shell cleanup verbs that are not in the active CLI surface.

Local Tunnels

When Codex starts a local service and needs a public URL, it should use the local MCP tunnel tool and treat the returned MCP result as the lifecycle record.

Start a small web server in this folder, expose it through rstream on the selected project, verify the public URL with curl, then stop the MCP-managed local tunnel and the local server.

For HTTP browser auth:

Expose this local HTTP service with browser rstream Auth, verify that an anonymous request does not serve the page directly, then clean up the tunnel.

For machine token auth:

Expose this local HTTP service with rstream token auth, verify that an anonymous request is rejected, then clean up the tunnel.

The MCP result includes the URL, applied options, resource ID, and cleanup fields. Cleanup should call the matching MCP stop tool with the returned ID. Codex should not invent a shell command for an MCP-managed local tunnel.

Advanced options follow the same model as rstream forward: token auth, rstream Auth, and challenge mode are HTTP edge options; stable domains and IP or Geo filters require a published tunnel; HTTP/3 is datagram-shaped while HTTP/1.1 and h2c are bytestream-shaped; TLS mode belongs to TLS tunnels. Codex should reject incompatible combinations before creating a tunnel.

Remote Machines

Expose a remote machine to Codex through WebTTY:

rstream webtty server --rstream --name homelab-macmini --label role=codex

Add filesystem access only when it is needed, and choose the narrowest root that makes sense:

rstream webtty server \
  --rstream \
  --name homelab-macmini \
  --label role=codex \
  --fs-root "$HOME/rstream-codex-lab"

The filesystem sidecar is rooted at --fs-root. If the server exposes ~/rstream-codex-lab, Codex should read /compose.yaml, not /home/user/rstream-codex-lab/compose.yaml.

Useful operator checks:

rstream webtty list --filter 'labels.rstream.webtty.label.role=codex' -o json
rstream webtty exec --url rstrm://homelab-macmini -- uname -a
rstream webtty fs ls --url rstrm://homelab-macmini /

For machines that must remain available, run WebTTY under the host's process manager: systemd on Linux, a LaunchAgent on macOS, a service wrapper or scheduled task on Windows, or a restart-managed container in homelab stacks.

Remote-Local Services and MCP

When a service only listens on a WebTTY host, Codex can ask local MCP to start a remote rstream tunnel from that host:

rstream_remote_expose(webtty_url="rstrm://homelab-macmini", exec_path="<exec_path>", port="8765", protocol="http")

For a device-local MCP server, include its path:

rstream_remote_expose(webtty_url="rstrm://homelab-macmini", exec_path="<exec_path>", port="8765", mcp_path="/mcp", publish=false)

That adds discovery labels so Codex can call rstream_remote_mcp_discover, rstream_remote_mcp_tools, and rstream_remote_mcp_call. Keep remote MCP exposures private unless a browser or external HTTP MCP client explicitly needs a public URL.

Application SDKs

MCP is an operator surface for Codex. Application code that owns tunnel lifecycle should use an SDK when the SDK covers the runtime.

Use a prompt like this when Codex is choosing an integration path:

This application owns tunnel creation, labels, access policy, reconnect, private dialing, and clean shutdown. Check rstream runtime status if useful, then choose the right rstream SDK and outline the lifecycle API. Do not use MCP or a CLI subprocess as the application's primary tunnel API.

Tokens and Browser Watch

Engine inventory endpoints such as /api/clients and /api/tunnels use:

Authorization: Bearer <token>

The Engine watch endpoints /api/sse and /api/websocket also accept rstream.token for browser transports that cannot attach headers. That query-token path is intentionally narrow: use a short-lived auth or app token with watch-only/list resources, not a broad personal token and not create/connect permissions.

Published HTTP tunnel token auth is separate from Engine API auth. A protected tunnel URL can accept token auth at the edge, while Engine API access still follows the Engine API token rules.

Knowledge Layering

Codex should not memorize the entire product in a single prompt. The durable model has three layers:

• MCP tool descriptions carry safety-critical rules before action.
• Agent Skills route Codex to the right setup, API, tunnel, WebTTY, troubleshooting, SDK, or self-hosted documentation.
• Product docs remain the detailed source of truth for feature matrices, edition boundaries, protocol details, SDK APIs, and security behavior.

This avoids copying every rule into every prompt while still letting Codex stop on incompatible, unavailable, or plan-gated combinations.

Safety Rules

WebTTY commands run as the user that launched the server unless the host explicitly permits another user. The filesystem sidecar is not a sandbox; it exposes the selected root through WebDAV and still runs with the server process permissions. For shared or production machines, run WebTTY as a dedicated user and choose a narrow filesystem root.

Use labels such as role=codex, site=lab, or device=pi-ha so Codex can select machines and tunnels by intent rather than generated hostnames.

For a complete walkthrough, see Use rstream as a Connectivity Layer for Codex. For remote terminal details, see WebTTY. For the broader discovery model, see Agent Native.