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.

The local MCP server then uses rstream_auth_start, shows the returned approval URL, and waits through 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.

For WebTTY, local MCP is the preferred path. Hosted MCP exists for agent runtimes that cannot execute the CLI at all. It can inventory WebTTY servers, create registered server records, run bounded commands against non-E2E targets, read session metadata, export non-E2E recordings, and coordinate control requests. It refuses E2E targets with an explicit local-trust error instead of receiving private keys or decrypting terminal data.

Project Setup

Codex prepares 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 lists the choices and asks for the project name, endpoint, or ID. It does not infer from naming conventions or add a preferred example.

Project creation is explicit. Codex first inspects creation options, shows the returned billing impact and next server-selected billing action, and only creates or starts 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 inspects 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 explains the exact limitation and suggests 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 does 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 reads 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 are 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 uses documented tunnel-management commands for inspection and does 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 uses the local MCP tunnel tool and treats 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 calls the matching MCP stop tool with the returned ID. Codex does 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 rejects incompatible combinations before creating a tunnel.

Remote Machines

Expose a remote machine to Codex through WebTTY:

rstream webtty server -v --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 -v \
  --rstream \
  --name homelab-macmini \
  --label role=codex \
  --fs-root "$HOME/rstream-codex-lab"

The filesystem sidecar is a separate file API next to command execution. It can list directories, read files, upload files, download files, or write files under --fs-root. If the server exposes ~/rstream-codex-lab, Codex reads /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 /

Use this lightweight WebTTY tunnel path for temporary machines, lab hosts, demos, and ad hoc agent work. It is label-driven and online-only.

For machines that must remain visible while offline, produce managed recordings, or use workspace-managed encryption, use a registered WebTTY server instead. When Codex is operating on the same machine that will run the server, create and enroll the server in one command:

rstream webtty server create homelab-macmini \
  --recording-policy recorded \
  --encryption-policy disabled \
  --label role=codex \
  --enroll
 
rstream webtty server -v --server-id <server-id>

For split-machine setup, create the registered server from the operator machine and run the printed Enroll command on the host that will run WebTTY.

For workspace-managed E2E, the Codex workstation must be a trusted workspace device. The connection resolves encryption at runtime; Codex does not ask the user to manually choose a key source for a registered server.

rstream workspace device enroll --kind agent --label codex-workstation
rstream workspace device status

Those commands use the workspace from the active project context. If Codex is not operating from an active project context, list workspaces first and pass --workspace <workspace-id> explicitly.

The filesystem sidecar is refused when WebTTY E2E is active. For agent workflows that need both encrypted terminal content and file operations, design a separate file path with its own security model instead of assuming the WebTTY sidecar inherits terminal E2E.

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 direct authenticated-E2E WebTTY URLs, pass known_server so the local MCP server can use the same pinned server identity and associated client identity as rstream webtty exec:

rstream_remote_expose(webtty_url="ws://127.0.0.1:8080", known_server="homelab-macmini", 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 uses 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 does not need the entire product model 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.