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 should run or be able to 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 should establish context before it starts touching resources. A good first prompt states the outcome you want; Codex should infer 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 should call the runtime preparation tool when no context is ready or when an old short-lived context token has expired, but it should 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 should also distinguish 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, and the rstream C++ SDK for native applications.

The division of knowledge should stay 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 should use 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 should 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 should 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 should report the limitation and propose 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.

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

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

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

rstream webtty server \
  --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 should survive logout or reboot, run the WebTTY server under the host process manager. Keep the service unit in the WebTTY 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. 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 should read /compose.yaml, not /srv/app/compose.yaml. The sidecar can be read-only with --fs-read-only; read-write is useful when you already allow command execution, 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 should verify the service from the remote host before creating a public or private rstream path. After exposure, it should verify the returned URL and compare 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 should list them but stop 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 should 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 should use the local MCP server instead of pasted tokens, request broader OAuth permissions only when the next operation needs them, and check plan or usage data before relying on plan-gated behavior.

Use labels on every resource Codex creates. Labels should 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 should verify the endpoint and keep the cleanup action tied to the tool result. The user should be able to say "cut the tunnel" and have Codex call the matching MCP cleanup tool; Codex should 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 should run WebTTY as an appropriate user and expose the narrowest useful root.

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