Choose your platform

Platform setup: macOS, Linux and Windows via WSL2

The verified onboarding interface is Codex Desktop on macOS with its in-app browser. Standalone Codex CLI onboarding is unverified. The local codex executable remains a runtime dependency because the bridge launches codex app-server to retrieve the linked Desktop task's history.

These are advanced-user preparation commands, followed by the same Auth0, tunnel and ChatGPT setup on every platform. They are not an unattended installer. Inspect existing tools first; do not replace a working runtime or change provider accounts just to follow an example.

Platform status

Codex Desktop is not a required Linux package: the bridge needs a compatible local Codex CLI and the exact stored task it can read. A task created by a Windows or Mac app is not automatically present in a Linux/WSL task store. Do not link a task from another environment by guessing its ID or copying private state directories. Create/use a task in the target environment and verify its repository root. A remote Linux host cannot read your laptop repository without a separately prepared local checkout and task on that host.

macOS terminal

If Homebrew is already installed, these commands install the prerequisites it provides. Otherwise follow Homebrew's installation instructions first, or use each vendor's installer. Do not run this block inside PowerShell.

brew install git node cloudflared
node --version
npm --version
git --no-lazy-fetch --version
cloudflared --version

Continue with the shared JavaScript tools and release installation below. Set BRIDGE_HOST=mac in the private .env when configuring the bridge.

Linux terminal (Debian/Ubuntu example)

Other distributions need equivalent packages from their maintained repositories; do not run apt-get commands on RPM-based systems. These commands need sudo for OS packages, not for running the bridge.

sudo apt-get update
sudo apt-get install -y git curl ca-certificates
git --no-lazy-fetch --version

Stop if the Git probe fails or the version is below 2.48. Older distribution packages may be too old. Install a supported Git version using the Git project's Linux guidance, then rerun the probe; do not remove the bridge's no-lazy-fetch security guard.

Install Node.js meeting app/package.json (currently >=24.18.0) from the official Node.js download instructions, choosing Linux and your CPU architecture, or your existing version manager. Do not assume apt-get install nodejs provides a sufficiently new release. Verify node --version and npm --version before proceeding. If the required release is unavailable in your chosen source, stop and report that prerequisite rather than lowering it.

For cloudflared, the following uses Cloudflare's signed stable Debian repository. Inspect any existing repository configuration first. These commands add an OS package source; they do not create a tunnel or publish any repository content. Source: Cloudflare package instructions.

sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main' | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt-get update
sudo apt-get install -y cloudflared
cloudflared --version

Set BRIDGE_HOST=linux. Keep grants, credentials and repository files on a local filesystem that enforces POSIX ownership and restrictive modes. Do not run the bridge as root or loosen permissions to make a failed check pass.

Windows: prepare WSL2 in PowerShell, then use Linux

In an administrator PowerShell window, first inspect existing distributions:

wsl --list --verbose

If a suitable WSL2 distribution is already present, use it. Otherwise, on a Windows version supported by Microsoft, install Ubuntu and restart if requested:

wsl --install -d Ubuntu

Open Ubuntu, complete its local Linux-user setup, and confirm version 2 with wsl --list --verbose in PowerShell. If it reports version 1, follow Microsoft's conversion instructions rather than assuming it is WSL2. Source: Microsoft WSL installation.

All remaining commands run in Ubuntu's Linux terminal, not PowerShell. Follow the Linux section above and the shared steps below. Store the checkout under the Linux home directory (for example ~/projects/context-relay), not /mnt/c, so Windows-mounted filesystem permissions do not undermine the bridge's file checks. Install and sign into the Linux Codex CLI there. Use a Codex task created in that same environment; Windows Desktop task-history access from WSL is not verified by this guide.

Run cloudflared in the same WSL distribution as the bridge. Its route targets http://127.0.0.1:3487 inside that environment (or your selected local port). ChatGPT in your ordinary Windows browser connects to the public HTTPS MCP URL. Windows sleep or stopping WSL interrupts access. Native Windows service startup and automatic WSL startup are not configured by this release.

Recovering an existing grant directory

If setup reports Grant directory must be owner-only, inspect ~/.config/codex-pro-bridge/links locally. This release uses that fixed path; BRIDGE_GRANTS_DIR is not a supported configuration option. The directory must be real, not a symlink, owned by the bridge user, with mode 700. After verifying the exact path and intended bridge user, repair that directory's ownership if needed, then set its mode to 700. Ownership repair may require administrator help. Do not recursively change permissions or use chmod 777. Directory repair alone does not repair existing grant files. Each grant must also be a regular file owned by the bridge user with no group/other permissions (normally mode 600). If existing links still fail these checks, create replacement links as the bridge user and obtain fresh approvals for their scope and untracked files. Do not copy or automatically change the old grants. If repair is impossible, stop setup and obtain the operator's approval before moving the directory aside or removing it, then recreate it as the bridge user with mode 700. Moving it aside makes existing links unavailable until restored; removal permanently discards the stored grants and revokes those links. Neither action retracts context already delivered to ChatGPT. Never delete grants as an automatic recovery step. A separate checkout does not isolate this store. See the second-installation requirements.

Shared JavaScript tools and source installation

In macOS or Linux/WSL Bash, after Node/npm and Git meet the requirements:

npm install -g corepack @openai/codex
corepack pnpm --version
codex --version
codex app-server --help

Use your normal development user and a writable npm tool installation. If npm reports a permission error, fix your user-level Node setup instead of running the bridge with sudo. Inspect an existing Corepack/Codex installation before upgrading it. The package manager is pinned to 11.24.0 by the repository; verify that version again from app/ after cloning. Source for the Codex CLI installation: OpenAI Codex CLI.

mkdir -p ~/projects
cd ~/projects
git clone --branch v0.4.0 --depth 1 https://github.com/digitalpilipinas/context-relay.git
cd context-relay/app
corepack pnpm --version
corepack pnpm install --frozen-lockfile
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build

If the target already exists, inspect it or choose a fresh folder; never overwrite an existing install. For an extracted release archive, enter its app/ directory and begin with the pnpm commands. A detached Git HEAD is expected for a release. Sign into the Codex CLI through its supported interactive flow before asking it to create or read an authenticated task; an installed executable alone is not proof of task-history access.

Now follow setup steps 2–6: configure your own Auth0 API/client/user, private .env, tunnel and ChatGPT connection. Choose mac or linux as above. Do not start with invented tenant values or reuse another operator's credentials.

After configuration, in the first macOS/Linux/WSL terminal, from app/:

corepack pnpm run doctor
corepack pnpm start

Before starting the tunnel, run cloudflared --version and confirm 2025.4.0 or newer, and run cloudflared tunnel run --help to confirm --token-file is available. If either check fails, update through your selected package source and recheck; do not paste a token into a shell command as a workaround. See Cloudflare token-file requirements.

In a second terminal in the same OS environment, after saving your tunnel token privately at the path used in the setup guide:

cloudflared tunnel --no-autoupdate run --token-file "$HOME/.config/codex-pro-bridge/tunnel.token"

Run health, OAuth, synthetic context and denial checks from the verification guide. Report each OS independently. Shell syntax checks or tests on macOS do not establish Linux/WSL acceptance. Installation commands were reviewed against vendor guidance; no Linux or Windows live run is claimed here. The same guided progress updates and manual credential/consent handoffs apply on all platforms.