remodex-windows-fix

Windows-friendly mirror of remodex with a launcher fix for codex app-server.

What Changed

• Fixes Windows startup when remodex up tries to spawn codex and fails with spawn codex ENOENT.
• Prefers codex.cmd or codex.bat on Windows and runs them with shell support.
• Falls back to codex.exe when a wrapper script is not present.
• Adds REMODEX_CODEX_BIN and PHODEX_CODEX_BIN overrides for explicit Codex binary selection.
• Prevents immediate uncaught startup crashes by routing launcher failures through Remodex error handling.

Why This Exists

On Windows, codex is often installed through npm as a .cmd shim. A plain Node spawn("codex", ["app-server"]) call can fail even when codex works in PowerShell. This fork resolves the executable explicitly before launching the bridge.

Install

Install from npm:

npm install -g remodex-windows-fix

Global CLI command:

remodex-windows-fix

The iPhone app is available on the App Store.

Usage

Start the bridge:

remodex-windows-fix up

Reset the saved pairing state and force a brand new QR:

remodex-windows-fix reset-pairing

Resume the last active thread:

remodex-windows-fix resume

Watch rollout output:

remodex-windows-fix watch [threadId]

macOS service commands inherited from upstream:

remodex-windows-fix start
remodex-windows-fix restart
remodex-windows-fix stop
remodex-windows-fix status

Get a fresh QR on Windows without stale pairing state:

run-clean-qr.bat

This helper:

• stops any existing remodex-windows-fix bridge process
• runs reset-pairing
• starts a fresh bridge in a new PowerShell window
• waits for C:\Users\%USERNAME%\.remodex\pairing-qr.png and opens it automatically

It defaults to:

wss://remodex-relay.th07290828.workers.dev/relay

You can also pass a custom relay URL:

run-clean-qr.bat wss://YOUR-RELAY/relay

Pairing Behavior

The bridge now keeps a stable saved relay session id, so you only need to scan the QR once per paired iPhone in normal use.

After the first QR pairing:

• you can stop and start remodex-windows-fix up again
• the same trusted client can reconnect without rescanning
• you can bootstrap an additional trusted browser client with a fresh QR
• you do not need a fresh QR unless you intentionally reset pairing

Use remodex-windows-fix reset-pairing when you want to:

• pair a different iPhone
• discard the saved trust/session state
• force a brand new QR bootstrap

Windows Override

If you want to force a specific Codex binary, set one of these environment variables before running remodex up:

$env:REMODEX_CODEX_BIN = "C:\Users\th072\AppData\Roaming\npm\codex.cmd"

Legacy alias:

$env:PHODEX_CODEX_BIN = "C:\Users\th072\AppData\Roaming\npm\codex.cmd"

Self-Hosted Relay

This repository now includes the upstream-compatible relay code and a local runner.

Start your own relay:

npm run relay

Or use the bundled binary directly:

remodex-relay

Docker Compose:

docker compose up -d

Browser client skeleton:

http://YOUR_HOST:9000/app/

The Node relay now serves a PWA shell at /app/ so you can start building a browser-based client on the same origin as the relay. Current scope:

• imports pairing JSON directly
• attempts QR image decoding through BarcodeDetector when the browser supports it
• opens a browser WebSocket as role=iphone
• persists relay/pairing state locally

Current limitation:

• the browser secure pairing handshake (clientHello / clientAuth / encrypted envelopes) is scaffolded in the UI only and is not implemented yet

Optional relay host/port overrides:

$env:REMODEX_RELAY_HOST = "0.0.0.0"
$env:REMODEX_RELAY_PORT = "9000"

Optional relay hardening overrides:

$env:REMODEX_TRUST_PROXY = "true"
$env:REMODEX_RELAY_EXPOSE_DETAILED_HEALTH = "true"
$env:REMODEX_RELAY_UPGRADE_WINDOW_MS = "60000"
$env:REMODEX_RELAY_UPGRADE_MAX_PER_WINDOW = "60"

Point the bridge at your relay:

$env:REMODEX_RELAY = "ws://YOUR_HOST:9000/relay"
remodex-windows-fix up

For TLS/reverse-proxy setups, use the public wss://YOUR_DOMAIN/relay URL instead.

Health endpoint:

GET /health

By default the relay returns a minimal health payload. Set REMODEX_RELAY_EXPOSE_DETAILED_HEALTH=true if you want /health to include session counters for monitoring.

Cloudflare Deploy

This repository also includes a Cloudflare Workers relay implementation in cloudflare/worker.mjs with Durable Objects configured in wrangler.toml.

GitHub itself still does not host persistent WebSocket servers, but Cloudflare Workers can deploy this relay directly from your GitHub repository without running anything locally.

The Worker also accepts browser iphone clients through ?role=iphone, which is necessary because browser WebSockets cannot send the x-role header.

The same Worker deployment now also serves the browser client shell at:

https://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/app/

Import this repository in Cloudflare:

1. Open Cloudflare Workers & Pages.
2. Create or import a Worker from your GitHub repository.
3. Use the worker name remodex-relay so it matches wrangler.toml.
4. Deploy the repository as-is.
5. After deploy, use the public Worker URL as the relay base:

$env:REMODEX_RELAY = "wss://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/relay"
remodex-windows-fix up

Current deployed example for this repository:

$env:REMODEX_RELAY = "wss://remodex-relay.th07290828.workers.dev/relay"
remodex-windows-fix up

If you are using cmd.exe instead of PowerShell:

set REMODEX_RELAY=wss://remodex-relay.th07290828.workers.dev/relay
remodex-windows-fix up

Health check:

https://remodex-relay.th07290828.workers.dev/health

Cloudflare health endpoint:

GET /health

Alternative GitHub Deploy

If you prefer a normal Node web service instead of Workers, this repository still includes the Render-compatible runner in render.yaml.

$env:REMODEX_RELAY = "wss://YOUR-SERVICE.onrender.com/relay"
remodex-windows-fix up

Validation

Typical local verification:

codex --version
codex app-server --help
remodex-windows-fix up

Expected Windows resolution after the fix:

C:\Users\th072\AppData\Roaming\npm\codex.cmd app-server

Project Layout

bin/
cloudflare/
compose.yaml
Dockerfile
relay/
src/
web/
wrangler.toml
package.json

Attribution

This repository preserves the upstream Remodex package structure and credits the original package author in package.json. This fork adds a Windows launcher compatibility patch and accompanying documentation.