CodexRelay
// Setup Guide

Real setup requirements,
real commands.

Open CheckoutOpen Dashboard
Supported hosts

macOS, Linux, and Windows are all valid host environments for the bridge launcher.

Required tools

Users need Node 20+ and npm. They do not need to clone the CodexRelay repo just to run the bridge.

Important note

The launcher command is cross-platform. Shell commands sent through the relay are still OS and shell specific.

// Install Node 20+
macOS

Use Homebrew to install Node 20+, then verify Node and npm.

brew install node@20
brew link --force --overwrite node@20
node -v
npm -v
Ubuntu / Debian

Use the NodeSource installer for Node 20+, then verify Node and npm.

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v
npm -v
Windows (PowerShell)

Install the LTS Node package with winget, then verify Node and npm.

winget install OpenJS.NodeJS.LTS
node -v
npm -v
// Quick Start
Verify Node 20+
node -v
npm -v
Open the folder you want to work in
cd /path/to/your/project
Run the bridge command from the dashboard
npx -y https://codexrelay.app/downloads/codexrelay-bridge-1.0.1.tgz --api https://codexrelay.app --session <SESSION_ID> --pair-code <PAIR_CODE> --daemon
// Pair A Host
  1. 01

    Open CodexRelay in the browser and create a session.

  2. 02

    Copy the bridge command from the dashboard.

  3. 03

    Run that command inside the folder you want the host to work in.

  4. 04

    Keep the host online if you want the relay to remain reachable.

// Bridge Command Shape

The dashboard generates the exact command for each session. It should be run inside the folder you want the host to use:

npx -y https://codexrelay.app/downloads/codexrelay-bridge-1.0.1.tgz --api https://codexrelay.app --session <SESSION_ID> --pair-code <PAIR_CODE> --daemon

Optional: add --codex for Codex mode.

Optional: add --shell if you want raw shell execution enabled.

Behavior: the daemon keeps using the folder where you launched the command.

Reminder: `--shell` is powerful and should only be used on trusted machines.

// Before You Run It

People should be skeptical of remote-agent launch commands. The point of this page is to make the trust boundary explicit before anyone pastes the bridge into a terminal.

Package source: the launcher is fetched from https://codexrelay.app/downloads/codexrelay-bridge-1.0.1.tgz.

Working scope: the bridge uses the folder where you launch the command as its working directory.

Local logs: daemon output is written on the host under ~/.codexrelay/logs.

Cut access fast: revoke the session in the dashboard or stop the local bridge process.

// What "Secure" Means Here

Not a black box: this is a Node launcher invoked with npx, not a hidden cloud desktop.

Stored session data: session messages are encrypted at rest on the server and session secrets are stored as hashes.

Browser access: production auth cookies are HttpOnly and Secure, and the API only accepts trusted origins.

Risk callout: --shell is intentionally powerful and should only be enabled for machines you trust.

// Codex Mode

Bridge only: Node 20+ is enough.

Codex mode: the host also needs the codex CLI installed and working in that terminal.

Quick check: run codex --version before launching with --codex.

If that command fails: the bridge will not be able to start Codex mode on that machine yet.

// Common Error

Error: spawn codex ENOENT

Meaning: the bridge tried to run codex, but the host machine could not find that executable.

Usually this means: Codex CLI is not installed, or it is installed but not available in the current PATH.

Windows note: if Codex was installed with npm, the binary is often under C:\Users\<You>\AppData\Roaming\npm. That folder must be in PATH.

// Verify Codex CLI
codex --version
command -v codex

If both commands work, Codex mode should be available from that terminal.

// Windows PATH Fix
$env:PATH = "C:\Users\<You>\AppData\Roaming\npm;$env:PATH"
codex --version

If that works, restart the bridge from the same PowerShell window or add that npm folder to your permanent user PATH.

// Next Step

Ready to pair a machine?

Buy a plan, create a session, and copy the generated bridge command from the dashboard.

Go To CheckoutOpen Dashboard