remote-jcodex

Open your local Codex app session from a phone or another browser.

npx remote-jcodex

remote-jcodex starts a token-protected browser bridge, prints local and LAN URLs, and shows a QR code. Tailscale is optional: when it is installed and online, the CLI also configures Tailscale Serve and uses the private Tailnet URL for the QR code.

Shared URLs use a short path token:

http://192.168.1.8:8214/t/<token>

The token is also stored in an HTTP-only cookie when the browser accepts it, so refreshes can keep working after the first open.

Requirements

• macOS 14 or newer
• Node.js 20.19 or newer; Node.js 22.12 or newer is recommended
• Codex CLI 0.128.0 or newer, already logged in locally
• internet access on first run to prepare the cached Codex web runtime

Linux and Windows are not currently supported. The runtime preparation downloads the Codex-darwin-arm64 desktop runtime. Archive extraction and patching use package-local Node tooling instead of system unzip or patch.

Tailscale is optional. Without it, the phone and host machine must be on the same local network.

Check the local setup without starting the bridge:

npx remote-jcodex --check
npx remote-jcodex -c

Usage

Run with defaults:

npx remote-jcodex
bunx remote-jcodex

Use another port or bind address:

npx remote-jcodex --port 9000
npx remote-jcodex -p 9000
npx remote-jcodex --host 127.0.0.1 --port 9000
npx remote-jcodex -H 127.0.0.1 -p 9000

Share a single Codex chat/thread:

npx remote-jcodex --thread <chat-id>
npx remote-jcodex -t <chat-id>
npx remote-jcodex --chat <chat-id>

Show diagnostics or logs:

npx remote-jcodex --debug
npx remote-jcodex -d
npx remote-jcodex --logs
npx remote-jcodex -l

Refresh or clear the cached web runtime:

npx remote-jcodex --update-runtime
npx remote-jcodex -u
npx remote-jcodex --clear-cache
npx remote-jcodex -C

Show help:

npx remote-jcodex --help
npx remote-jcodex -h

The CLI checks npm on startup and re-runs remote-jcodex@latest when a stale bunx or npx copy starts. Set REMOTE_JCODEX_SKIP_LATEST_CHECK=1 only for offline debugging with a known local version.

Options

--host, -H <host>      Bind address. Default: 0.0.0.0
--port, -p <port>      Bridge port. Default: 8214
--thread, -t <id>      Open and lock the bridge to one chat/thread
--chat <id>            Alias for --thread
--check, -c            Verify requirements without starting the bridge
--debug, -d            Print startup, health, and sharing diagnostics
--logs, -l             Write logs and show the bridge log path
--update-runtime, -u   Rebuild the cached Codex web runtime
--clear-cache, -C      Delete the remote-jcodex cache before running
--help, -h             Show command usage

Environment

REMOTE_JCODEX_HOST=127.0.0.1 npx remote-jcodex
REMOTE_JCODEX_PORT=9000 npx remote-jcodex
REMOTE_JCODEX_DEBUG=1 npx remote-jcodex
REMOTE_JCODEX_SHOW_LOGS=1 npx remote-jcodex
REMOTE_JCODEX_CACHE_DIR="$HOME/.cache/remote-jcodex" npx remote-jcodex
REMOTE_JCODEX_ACCESS_TOKEN="shared-secret" npx remote-jcodex
REMOTE_JCODEX_THREAD_ID="<chat-id>" npx remote-jcodex
REMOTE_JCODEX_SKIP_LATEST_CHECK=1 npx remote-jcodex

REMOTE_JCODEX_ACCESS_TOKEN is optional. If it is not set, each run generates a new random token.

Sharing

Local Network

Local network sharing is the default.

Network   http://192.168.1.8:8214/t/<token>

Scan the QR code or open the printed Network URL on the phone. remote-jcodex listens on 0.0.0.0 by default so other devices on the LAN can reach it. Use --host 127.0.0.1 only when you want local-machine-only access.

Tailscale

When Tailscale is installed and online, remote-jcodex configures Tailscale Serve to point at the current local bridge port.

Tailnet   https://<device>.<tailnet>.ts.net/t/<token>

The QR code uses the Tailnet HTTPS URL when Tailscale Serve is active. This is useful when the phone is not on the same Wi-Fi network but is connected to the same tailnet.

The CLI does not log in to Tailscale, connect it, disconnect it, or shut it down. If Tailscale is unavailable or offline, the CLI continues with the LAN URL.

Scoped Chat

Use --thread <id> or --chat <id> to share only one Codex chat/thread.

Scoped mode:

• opens the browser directly to the selected thread
• includes the thread in printed URLs and the QR code
• redirects browser navigation back to the scoped thread
• blocks renderer IPC payloads that explicitly target another thread ID

This is a guard for casual sharing. Treat the scoped URL as sensitive because it still operates the local Codex session.

Behavior

• binds to 0.0.0.0:8214 by default
• generates a per-run access token and includes it in printed URLs and QR codes
• accepts /t/<token> plus legacy ?t=<token> and ?remote_jcodex_token=<token>
• stores the token in a cookie when the browser accepts it
• health-checks the bridge before printing the summary
• prints local, LAN, optional Tailnet, and proxy status
• writes logs only with --logs, -l, or debug mode
• shows a QR code for Tailnet when available, otherwise LAN
• applies mobile webview fixes for touch scrolling and Enter-as-newline
• leaves Tailscale Serve configured as a persistent bridge when available
• stores the runtime cache at ~/.remote-jcodex/runtime by default

Troubleshooting

Use debug mode when the phone cannot open the URL:

npx remote-jcodex -d

Debug mode prints the selected host, port, health checks, Tailscale availability, Serve setup, and log path. Use --logs or -l when you only need the log file.

Common checks:

• Phone and host are on the same network when using the LAN URL.
• The first opened URL includes /t/<token>.
• Local firewall rules allow inbound connections to the selected port.
• If a Tailnet URL returns HTTP 502, restart remote-jcodex so Serve points at the current bridge port.
• Run npx remote-jcodex --check to verify local requirements.

Security

The LAN and Tailnet URLs can operate Codex as your local macOS user. Treat the token URL as sensitive, share it only with trusted devices, and do not expose it with Tailscale Funnel or a public reverse proxy.

The bridge rejects browser, static-file, upload, and WebSocket requests that do not present the token or token cookie. The token protects access to the bridge; it does not make an untrusted network safe.

License

Source-available proprietary license: LicenseRef-RemoteJCodex-Source-Available.

You may install and use the unmodified npm package for personal, evaluation, or internal business use. Redistribution, repackaging, resale, hosted-service use, and publishing modified copies are not allowed. See LICENSE.