OpenCodex: browser access to Codex Desktop from a phone or another machine

The gap OpenCodex fills for Codex Desktop users

Codex Desktop is a local application. Its session, file tree and terminal live on the machine where it is installed, and the README describes OpenCodex as a middleware layer that makes that same runtime reachable from a browser. The stated audience is people who want to keep coding with Codex while away from the desk: a phone, a tablet, or another computer on the same network.

The README is candid about why this still matters after the ChatGPT app added Codex support. Its four listed advantages are no need for a circumvention network, no need for a foreign Google Play or Apple account (and support for third-party API logins), access to the full Codex feature set such as the file tree, terminal and review views, and freedom to pair it with your own tunneling or public network instead of an official relay. That last point is the one with real consequences: traffic goes over the path you choose, not through a vendor's servers.

This is a self-hosted tool, not a service. It does not provide remote access by itself. The README says so directly and points at Tailscale, ZeroTier, Cloudflare Tunnel or a self-built VPN as the network layer, with LAN mode enabled in the launcher.

How the gateway sits between the browser and the desktop runtime

The repository splits into a gateway, a launcher, a web-shell front end, a shared package and an sdk directory, with pnpm workspaces tying them together. The gateway is the process that listens for HTTP and WebSocket traffic; the launcher is an Electron app that starts and supervises it.

On startup the gateway scans for a local Codex or ChatGPT Desktop installation and unpacks the official bundle into a cache directory, then runs the official runtime in an isolated profile. The environment table exposes the pieces: CODEX_WEB_OFFICIAL_BUNDLE_DIR for the unpack cache, CODEX_WEB_OFFICIAL_USER_DATA_DIR for the isolated Electron profile, and CODEX_WEB_OFFICIAL_TMPDIR for a temporary directory used to keep the official IPC socket separate. CODEX_WEB_OFFICIAL_AUTO_SCAN_UPGRADE defaults to 1, which means the gateway rescans the official runtime at startup; setting it to 0 makes it reuse the existing cache unless the cache is missing or unusable.

That design explains the compatibility claim in the README: because it follows the locally installed desktop runtime rather than pinning its own copy, it can track new versions of the app. It also explains the failure surface. If the desktop app is not installed, or the scan picks the wrong path, the runtime has nothing to wrap. The environment table exists precisely for those cases, with CODEX_DESKTOP_APP_PATH, CODEX_DESKTOP_EXECUTABLE_PATH, CODEX_APP_SERVER_BINARY_PATH and CODEX_CLI_PATH available as manual overrides.

Authentication is handled in the gateway with a token whose lifetime is controlled by CODEX_WEB_AUTH_TOKEN_TTL_MS, defaulting to 43200000 milliseconds, or twelve hours. A config file, located through CODEX_WEB_CONFIG_PATH and defaulting to config.yaml, holds the password. The README's own advice is blunt: set an access password and change the port.

Installing OpenCodex and reaching the first session

Two paths exist. The launcher is an installable desktop application, and the README recommends the Release channel as the more stable option, with GitHub Actions Artifacts as a test channel that requires a GitHub login to download. macOS users hitting the first-launch security prompt are pointed at docs/macos-installation.zh.md. There is no prebuilt launcher for Linux; the README directs Linux users to the command line and to docs/LINUX_GUIDE.md.

The command-line route is the one you can reproduce from the README. It requires Node and pnpm, plus a local install of either the old Codex Desktop or the new ChatGPT Desktop. The desktop app does not have to be running. Install dependencies first:

pnpm install

For a LAN-only session, start the gateway on port 3737. The README uses this exact form:

PORT=3737 pnpm run web:dev

To accept connections from other hosts, bind to all interfaces. The README warns in bold that you should set an access password and change the port before doing this:

HOST=0.0.0.0 PORT=3737 pnpm run web:dev

Password setup is a copy and an edit. The example config ships in the repository root:

cp config.example.yaml config.yaml

The key the README shows is auth.password:

auth:
  password: "你的密码"

Once the gateway is up, browse to http://127.0.0.1:3737. If the page does not load, the README suggests checking the health endpoint before anything else:

curl http://127.0.0.1:3737/api/health

If the port is taken, the documented fix is to start on another one, for example PORT=3738. Launcher builds for macOS and Windows are produced with pnpm run launcher:dist:mac and pnpm run launcher:dist:win, with output in release/. The launcher picks a random free port on first start and restarts the service when you change the listen address, port or password. For local launcher debugging, pnpm run launcher:dev is the documented command.

Where OpenCodex breaks down or is the wrong choice

The most concrete limitation is stated in the README's own FAQ: if you run OpenCodex and the official desktop app at the same time, each maintains its own session state. The data is the same, but the two views may not stay in real time sync. The recommended workaround is to use OpenCodex alone, locally or remotely, optionally installed as a PWA. If your workflow depends on the native desktop window and the browser view agreeing at all times, this is not the tool for that.

First load can be slow. The FAQ attributes an empty session history on first open to load time and to the speed of the remote LAN link, and suggests waiting and refreshing. That is a network-sensitive design, not a rendering bug you can patch away.

Security is your responsibility. The README advises against exposing OpenCodex directly to the public internet and recommends Tailscale, ZeroTier, Cloudflare Tunnel or a self-built VPN instead. The gateway supports a password, but the README treats an unauthenticated exposure as a mistake to avoid, not a supported mode. Anyone who reaches the port and the password reaches a runtime that has file tree and terminal access on that machine.

Finally, the tool depends on a desktop app being present on the target machine. If your environment cannot install Codex Desktop or ChatGPT Desktop, or you want a purely headless Linux box with no Electron runtime, the middleware has nothing to attach to. The Linux guide is a command-line path, but the desktop prerequisite still applies.

How OpenCodex differs from running Codex through the official ChatGPT app

The README's own framing is that the official ChatGPT app now supports Codex, which removes the original reason the project existed. What remains is a difference in routing and control, not in the underlying model.

With the official app, the client talks to the vendor's infrastructure and the remote path is the vendor's relay. OpenCodex instead serves the runtime from your machine and leaves the transport to you. That changes three things. First, reachability: a Tailscale or ZeroTier address on your own network does not depend on a third-party relay being available, and the README notes no circumvention network is needed. Second, account requirements: the project supports third-party API logins and does not require a foreign app store account, which matters if your ChatGPT or Codex access is provisioned that way. Third, surface area: you get the desktop feature set in the browser, including the file tree, terminal and review views, rather than a mobile-shaped subset.

The trade is operational. You now own a Node process, a config file with a password, a port, and a network path. The official app owns none of that for you. If you do not want to run and patch a gateway, the official client is the lower-effort answer; if you want the desktop runtime reachable over your own network, OpenCodex is the one that does it.

Maintenance cost, version coupling and the AGPL-3.0 licence

The repository was last pushed on 2026-09-13, the same day as the 2.1.0 release, with 2.0.3 on 2026-07-31 and 2.0.2 on 2026-07-10 before it. It is not archived. The release cadence visible in the repository is roughly monthly to six-weekly, and version bumps are synchronized across the workspace by scripts/sync-app-version.cjs, exposed as pnpm run sync:version, with pnpm run check:version to verify consistency.

The maintenance burden that matters is not the OpenCodex code itself but the official runtime it wraps. The gateway follows the locally installed Codex or ChatGPT Desktop version, and CODEX_WEB_OFFICIAL_AUTO_SCAN_UPGRADE defaults to 1 so it rescans at startup. When the desktop app updates and something in the wrapped runtime changes shape, OpenCodex has to catch up. The test list in package.json shows how much of the project is compatibility plumbing: official-desktop-compat, official-runtime, official-electron-module-hook, compatibility-registry and compatibility-service all appear as test files. Budget for occasional breakage after a desktop app update, and for the manual path overrides when auto-scan picks the wrong binary.

Licensing is AGPL-3.0. The package.json marks the package private. For internal use this is typically unremarkable. If you plan to offer a modified OpenCodex as a network service to others, the AGPL's network clause is the part to read carefully with your own counsel. Nothing here is legal advice; the licence text in LICENSE is the authority.

Upgrades themselves are cheap if you use the Release channel, since the launcher restarts the service when configuration changes. The risk sits in the wrapped runtime, not in the install.

Editorial conclusion

Adopt OpenCodex if a Codex or ChatGPT Desktop install already lives on a machine you leave running and you want to drive it from a phone or a second laptop without going through an official relay. Do not adopt it if you want a hosted service, if the target machine cannot keep the desktop app installed, or if you need two clients to stay in sync in real time. Before installing, confirm the desktop app is present, decide whether you will run the launcher or the CLI, and set a password in config.yaml rather than leaving the gateway open.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. Releases
5. RyensX/OpenCodex on GitHub