Codex

rstream can give Codex a controlled network path to machines and local services that do not expose inbound ports. The core pattern is simple: the operator machine keeps a normal rstream CLI context, Codex uses local rstream MCP tools, and remote devices opt in by running WebTTY with explicit capabilities.

This keeps the trust boundary local. Codex does not need a raw project token pasted into a prompt, and private tunnel dialing still goes through the same rstream context, token storage, permissions, and diagnostics used by the CLI.

Configure Codex

Start with a valid rstream CLI context:

rstream doctor -o json

Then register the local MCP server:

rstream codex setup

This writes a Codex MCP server entry that runs:

rstream mcp serve

The local MCP server exposes tools for WebTTY inventory, non-interactive command execution, and filesystem sidecar access. It uses the local rstream configuration, so it can dial private rstrm:// tunnels and does not depend on a browser session.

Prepare a remote machine

On the remote machine, run a WebTTY server over rstream:

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

For command execution only, that is enough. The server advertises rstream.webtty.capabilities=exec and rstream.webtty.exec.path=/.

When Codex also needs file access, enable the WebDAV sidecar with an explicit root:

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

The sidecar is read-write by default. Use --fs-read-only when Codex should inspect files without writing through the filesystem path.

Operate through the CLI

The same operations available to Codex through MCP are available directly from the CLI:

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 /
rstream webtty fs read --url rstrm://homelab-macmini /README.md

Agents should discover WebTTY capabilities from labels before using the filesystem tools. A server that only advertises exec should be treated as command-only.

Expose a local resource

When Codex starts a local web server and needs a temporary public URL, use a normal HTTP tunnel:

rstream forward 3000 --name codex-preview --label role=codex

For private service paths, keep the tunnel unpublished and connect through the native rstream dialer:

rstream forward 3000 --name codex-preview --no-publish --label role=codex

This separation matters. Public HTTP tunnels are useful for browser previews, webhooks, and third-party callbacks. Private tunnels are better for agent-to-agent or operator-only traffic where no browser-facing URL is required.

Safety rules

WebTTY commands run as the operating-system user that launched the server unless the host explicitly permits another user. The filesystem sidecar is not a sandbox; it exposes the selected --fs-root through WebDAV. For shared or production machines, run the WebTTY server as a dedicated user and choose the narrowest useful filesystem root.

Use labels such as role=codex, site=lab, or device=pi-ha to make inventory explicit. Avoid relying on generated hostnames as the only source of meaning, because labels are the stable selection surface across CLI output, engine APIs, and MCP tools.

For the WebTTY details behind this integration, see WebTTY. For the broader agent discovery model, see Agent Native.