Use rstream as a Connectivity Layer for Codex

This guide shows how to connect rstream to Codex as an agent-friendly network layer. Codex uses that layer to publish local services as managed local tunnels, expose resources over HTTP, WebSocket, TCP, TLS, UDP, QUIC, and other supported protocols, and reach remote machines behind NAT without opening inbound ports.

The walkthrough starts with the local rstream MCP server, then moves through WebTTY command execution, bounded filesystem access, remote-local service exposure, and device-local MCP servers. Each step keeps the boundary explicit: what Codex can do on its own, what needs user approval, and how temporary access is cleaned up.

Before You Start

You need an rstream account, rstream CLI 1.19.0 or later on the machine where Codex runs, a tunnel project, and Codex configured with local MCP support. For remote workflows, you also need a machine with outbound network access to rstream. For remote MCP workflows, that machine runs or can start an HTTP MCP server on its local network.

Start on the Codex workstation:

rstream doctor -o json
rstream login
rstream codex setup

rstream login opens the normal browser approval flow. If you prefer a Codex-native bootstrap, rstream codex setup can be run first and Codex can start the same OAuth device flow through MCP.

For long-lived servers, CI, and devices, avoid reusing a broad personal token when a project-scoped credential is enough. The CLI workflow and security docs cover those credentials in more detail; this guide focuses on the shape Codex uses once the resource can reach rstream.

Give Codex a rstream Control Surface

rstream codex setup registers a local MCP server that runs the rstream CLI on behalf of Codex. The underlying command is:

rstream mcp serve

That local MCP server can read the local rstream context, start the OAuth device flow, prepare the selected project runtime, list workspaces and projects, inspect plan and usage data, mint short-lived delegated tokens, start managed local tunnels, discover WebTTY servers, execute bounded remote commands, use the WebTTY filesystem sidecar, expose remote-local services, and bridge remote MCP servers.

Codex establishes context before it starts touching resources. A good first prompt states the outcome you want; Codex infers login, project selection, plan checks, and approval boundaries from the rstream MCP tools.

On a workstation, the correct setup path is the long-lived rstream login credential plus a linked project context. Codex calls the runtime preparation tool when no context is ready or when an old short-lived context token has expired, but it does not guess a project when several are available. With multiple projects, ask for the target project or use the one named in the prompt. Short-lived tokens are only for immediate handoff flows such as protected URLs, browser-constrained clients, published MCP access from a remote runtime, or one-shot startup commands on remote devices.

Codex also distinguishes operator workflows from application runtime design. Local MCP is the right control surface when Codex is operating the workstation, a remote WebTTY device, a temporary local tunnel, or a remote MCP bridge. When application code owns the tunnel lifecycle, use the SDK that matches the runtime instead of turning Codex or the CLI into an embedded API: @rstreamlabs/runtime for Node.js tunnel serving and private dialing, @rstreamlabs/tunnels for Engine inventory, watch streams, scoped tokens, and TURN helpers, github.com/rstreamlabs/rstream-go for Go services and devices, github.com/rstreamlabs/rstream-python for asyncio services and workers, github.com/rstreamlabs/rstream-java for JVM services, and the rstream C++ SDK for native applications.

The division of knowledge stays layered. MCP tool descriptions carry the guardrails Codex needs before acting. Agent Skills are compact routing instructions that tell Codex which docs to load for setup, tunnels, API, WebTTY, troubleshooting, or self-hosted work. The product docs remain the detailed source of truth for feature matrices, edition boundaries, protocol details, SDK APIs, and security rules. That avoids copying every rule into every prompt while still giving Codex enough context to stop on incompatible or plan-gated combinations.

The prompts in this guide describe the result you want. Codex chooses the rstream MCP tools, paths, and cleanup calls from the live inventory.

The hosted /api/mcp endpoint covers control-plane operations with an explicit bearer token. Managed local tunnels, private tunnel dialing, WebTTY execution, filesystem access, and remote service exposure use the local MCP server because they depend on the workstation rstream context and private dialer.

Expose Local Work Without Shipping It

The first resource to connect is usually a local service. Codex can update a Next.js app, start the local server, expose the development port through rstream, verify the returned URL, and keep the local tunnel available while someone reviews it.

The direct CLI form is a normal published tunnel:

rstream forward 3000 --name codex-local --label source=codex --label purpose=review

Through MCP, Codex uses the managed local tunnel registry so the tunnel can be listed and stopped after the current turn:

rstream_local_tunnel_expose(port="3000", name="codex-local")
rstream_local_tunnel_list()
rstream_local_tunnel_stop(id="<local-tunnel-id>")

The same pattern works in CI or another ephemeral environment. Keep the CI script small, attach metadata as labels, and stop the process at the end of the job.

rstream forward "${PORT:-3000}" \
  --name "ci-review-${GITHUB_HEAD_REF:-local}-${GITHUB_SHA:-manual}" \
  --label source=ci \
  --label purpose=review \
  --label branch="${GITHUB_HEAD_REF:-local}" \
  --label commit="${GITHUB_SHA:-manual}"

That makes the review URL discoverable without turning the guide into a GitHub Actions tutorial. A later CI-specific guide can cover artifact links, job summaries, branch cleanup, and provider-specific secrets.

Use rstream Auth for browser-facing local tunnels that redirect through the hosted login flow, token authentication for machine-facing HTTP tunnels, challenge mode for lightweight browser verification, and a stable domain when the external callback must stay stable across restarts. These are HTTP edge options for published tunnels. Codex does not apply them to raw TLS, TCP, UDP, QUIC, or private-only tunnels. If the selected project plan does not support the requested mode, Codex reports the limitation and proposes the closest available path before creating anything.

Give Codex Hands on Remote Machines

A homelab server, CI box, customer appliance, robot, or edge device can opt into rstream by running WebTTY. The machine initiates the outbound connection, so it can sit behind NAT or a private address while still becoming reachable to authorized rstream clients.

For temporary agent access, use a lightweight WebTTY tunnel. It is online-only and discovered through labels:

Start with a stable name and labels that describe how Codex finds the machine:

rstream webtty server -v \
  --rstream \
  --name edge-lab \
  --label role=codex \
  --label capability=docker

If Codex also needs file access, expose the narrowest useful root:

rstream webtty server -v \
  --rstream \
  --name edge-lab \
  --label role=codex \
  --label capability=docker \
  --fs-root /srv/app

Verify from the Codex workstation before asking Codex to operate the machine:

rstream webtty list --filter 'labels.rstream.webtty.label.role=codex' -o json
rstream webtty exec --url rstrm://edge-lab -- uname -a

For devices that survive logout or reboot and stay visible when offline, use a registered WebTTY server. The registration can be created from the Dashboard, CLI, or API. The CLI form is:

rstream webtty server create edge-lab \
  --recording-policy recorded \
  --encryption-policy disabled \
  --label role=codex \
  --label capability=docker
 
rstream webtty server enroll <server-id>
 
rstream webtty server -v --server-id <server-id>

Registered servers are the path for managed recordings, stable inventory, live session APIs, and workspace-managed E2E. For workspace-managed E2E, the Codex workstation must be enrolled as a trusted workspace device:

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

The commands use the workspace from the active project context. Use rstream workspace list and --workspace <workspace-id> only when Codex is not operating from an active project context or when the trusted device belongs to another workspace.

For devices that stay available, run WebTTY under the host process manager. Keep the service unit in the WebTTY operations guide or your infrastructure repo rather than burying it in this guide.

Use Remote Command and Filesystem Access

Once a WebTTY machine is online, Codex can use command execution for runtime state and the filesystem sidecar for files. The sidecar is a separate file API that can list directories, read files, upload files, download files, or write files under the configured root. Keep those paths separate, and pass the advertised exec_path and fs_path values to the matching MCP or CLI operation instead of assuming / and /fs. Commands are good for process state, logs, package versions, and health checks. The filesystem sidecar is better for reading configuration, transferring logs, uploading a patch, or writing a file after approval.

rstream webtty exec --url rstrm://edge-lab -- docker ps
rstream webtty fs ls --url rstrm://edge-lab /
rstream webtty fs read --url rstrm://edge-lab /compose.yaml
rstream webtty fs upload --url rstrm://edge-lab ./local.patch /uploads/local.patch
rstream webtty fs download --url rstrm://edge-lab /logs/app.log ./app.log

Paths are relative to --fs-root. If WebTTY starts with --fs-root /srv/app, Codex reads /compose.yaml, not /srv/app/compose.yaml. The sidecar can be read-only with --fs-read-only; read-write is useful when command execution is already allowed, but it still runs with the WebTTY process permissions and is not a sandbox.

Reach Private Services From the Agent Loop

Some useful resources are not files or shell output. A homelab Grafana, a local metrics endpoint, a device API, an admin UI, or a debug server may only listen on the remote machine. In that case Codex can expose the service from the WebTTY host.

The important detail is where the tunnel starts. If Codex exposes 127.0.0.1:3000 through rstrm://edge-lab, that address belongs to edge-lab, not to the Codex workstation.

rstream_remote_expose(
  webtty_url="rstrm://edge-lab",
  exec_path="<exec_path>",
  port="3000",
  name="edge-admin",
  labels=["source=codex", "purpose=remote-review"]
)

Codex verifies the service from the remote host before creating a public or private rstream path. After exposure, it verifies the returned URL and compares the remote-local response with the rstream response.

Bridge Remote MCP Servers

Remote MCP is the same pattern applied to an agent tool surface. A device can run an MCP server on its own loopback interface, keep it local by default, and expose it through rstream only when Codex needs to discover or call a tool.

Use mcp_path when creating the remote exposure so the tunnel advertises itself as an MCP surface:

rstream_remote_expose(
  webtty_url="rstrm://edge-lab",
  exec_path="<exec_path>",
  port="8765",
  name="edge-device-mcp",
  mcp_path="/mcp",
  token_auth=true,
  labels=["source=codex", "purpose=remote-mcp"]
)
rstream_remote_mcp_discover(filter="labels.purpose=remote-mcp")
rstream_remote_mcp_tools(url="rstrm://edge-device-mcp", path="/mcp")
rstream_remote_mcp_call(url="rstrm://edge-device-mcp", path="/mcp", tool="device_status")

Start with read-only tools such as status, inventory, diagnostics, or sensor snapshots. If a remote MCP server exposes mutating tools, Codex lists them but stops for approval before calling them.

When the useful surface is the workstation local rstream MCP server and a remote agent runtime cannot spawn a local stdio process, publish it through rstream:

rstream mcp publish --name codex-rstream-mcp --label role=codex

Published MCP endpoints stay token-protected and use a short-lived token scoped to that tunnel. When the client can attach headers, use Authorization: Bearer <token>. Use a rstream.token query parameter only where the protocol or browser client cannot attach headers, and mint it shortly before use with a narrow resource boundary for the MCP tunnel and path.

Access Boundaries, Approval, and Cleanup

The useful version of this workflow is controlled access, not open-ended remote control. Codex uses the local MCP server instead of pasted tokens, requests broader OAuth permissions only when the next operation needs them, and checks plan or usage data before relying on plan-gated behavior.

Use labels on every resource Codex creates. Good labels explain the source, purpose, service, branch, commit, device role, or task owner. They make local tunnels, remote services, and MCP bridges discoverable and cleanable.

Ask for approval before paid actions, public exposure of a sensitive service, file writes, package installs, service restarts, project setting changes, credential creation, or mutating remote MCP tools. After every exposure, Codex verifies the endpoint and keeps the cleanup action tied to the tool result. The user can say "cut the tunnel" and have Codex call the matching MCP cleanup tool; Codex does not invent a shell cleanup command for an MCP-managed resource.

rstream_local_tunnel_stop(id="<local-tunnel-id>")
rstream_remote_expose_stop(webtty_url="rstrm://edge-lab", exec_path="<exec_path>", id="<remote-expose-id>")

The same boundaries apply to the filesystem. --fs-root narrows the visible tree, but it is not a sandbox. Commands and filesystem access run with the permissions of the WebTTY server process, so long-lived machines run WebTTY as an appropriate user and expose the narrowest useful root.

Use the same workflow with Claude Code

The workflow is not specific to Codex. Claude Code uses the same rstream MCP server and the same tunnel, WebTTY, filesystem, and remote MCP tools. Only the local MCP registration differs:

rstream claude setup

This runs claude mcp add and registers rstream mcp serve at user scope. For a repository-scoped setup, Claude Code reads .mcp.json from the repository root; rstream claude setup --print shows both forms without changing the local configuration. The /mcp command confirms that the server is available in a Claude Code session.

Published and hosted MCP endpoints work through Claude Code's HTTP transport as well. A remote runtime can connect through rstream mcp publish or call the hosted /api/mcp endpoint with a bearer token. The access rules and cleanup steps in this guide remain unchanged. When labels identify the client explicitly, use role=claude in place of role=codex.

The detailed references are Codex, Claude Code, Agent Native, WebTTY, Access Remote Machines with rstream WebTTY, Expose a Local Next.js App with rstream, CLI Workflow, and Troubleshooting.