Library / SDK
RyensX/OpenCodex avatar
RyensX/OpenCodex

OpenCodex borrows a desktop runtime it never installs

OpenCodex is a middleware layer for Codex/ChatGPT Desktop. It lets you use a phone, tablet, or another computer to access and operate Codex on a target machine through a browser, making it suitable for continuous AI Coding in LAN or remote LAN environments.

734 stars79 forksJavaScriptAGPL-3.0

At a glance

What is it?
OpenCodex is a middleware layer that puts an already installed Codex Desktop or ChatGPT Desktop in a browser on your phone. It ships no runtime of its own, its two entry points bind differently, and it unpacks an official bundle that keeps upgrading itself.
Who is it for?
Check the bind address and the password before this reaches a network you do not control, because the command line path starts on HOST 0.0.0.0 with PORT 3737 and the password is a separate later step. Use it if you want a terminal, a file tree, and review panes on a phone over Tailscale, ZeroTier, or a company VPN, and you already have Codex Desktop or ChatGPT Desktop on the machine.
Can I use it commercially?
Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?
Yes. The repository last received commits 8 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 20, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • RyensX/OpenCodex734 ★ · +45
Star history
Repository2026-09-142026-11-20
RyensX/OpenCodex689734

45 Stars in the last 67 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

No runtime of its own: every feature runs through a desktop app you already installed

OpenCodex bundles no model runtime and no Codex binary. The stated requirement is that the machine already has either the older Codex Desktop or the newer ChatGPT Desktop installed, and that app does not have to be running. Everything else follows from that choice. package.json points its entry at launcher/main.cjs, the web UI lives in web-shell, and the repository is a pnpm workspace with gateway, sdk, shared, scripts, launcher, and web-shell directories. The front page also explains the shape of the project: the author had just finished preparing to open source a browser bridge for Codex Desktop when the ChatGPT app added Codex support itself. The comparison the project now draws is against an official product that grew the same capability. The four points listed there are avoiding an external network, avoiding a foreign app store account while still allowing third party API logins, exposing the full Codex surface such as the file tree, terminal, and review, and routing through your own tunneling rather than the official relay server. The launcher also follows the local Codex or ChatGPT Desktop runtime version at startup, so a change on the official side can alter behaviour here without a release from this project.

The command line gateway binds every interface before it asks for a password

The two ways to start this project do not begin from the same place. The command line gateway reads HOST, whose default is 0.0.0.0, and PORT, whose default is 3737. The launcher reads a different pair: OPENCODEX_HOST, defaulting to 127.0.0.1, and OPENCODEX_PORT, defaulting to a random available port. The documented local network start is the gateway, so the quickstart route leaves HOST on its wildcard default, and the password step is written after it. Copying the example config is a separate action, and the only content shown for it is an auth block:

yaml
auth:
  password: "你的密码"

CODEX_WEB_CONFIG_PATH decides which file is read, and its default is config.yaml. Read in order, the guide puts an unauthenticated listener on every interface one step before it recommends setting a password. The launcher carries the safer default, yet the troubleshooting commands near the end of the front page assume the gateway rather than the launcher:

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

If that port is taken, the same page offers a different one:

bash
PORT=3738 pnpm run web:dev

In the launcher, changing the listen address, the port, or the access password restarts the service so the new value takes effect.

Two download channels, one behind a GitHub login, and no Linux build

Stable builds come from the GitHub Releases page. Test builds come from Actions Artifacts, which CI produces on every push and which need a GitHub login to open at all. package.json sets private to true, so there is no registry channel and no installable package name; the README front page lists the release link and the artifacts link as the two channels and labels the release channel the more stable one. Locally the launcher has its own build scripts: pnpm run launcher:dev for a development start, pnpm run launcher:dist:mac and pnpm run launcher:dist:win for installers, with output written to a release/ directory. Linux appears in the supported systems list but has no prebuilt launcher, and Linux users are pointed at the command line path and docs/LINUX_GUIDE.md. macOS has its own document for the first launch security prompt at docs/macos-installation.zh.md. Version numbers are not left to hand either: pnpm run sync runs scripts/sync-app-version.cjs, and pnpm run check:version runs the same script with a check flag. package.json reports 2.1.0, tag v2.1.0 is dated 2026-09-13, and the two earlier tags are 2.0.3 from 2026-07-31 and 2.0.2 from 2026-07-10.

It unpacks the official bundle, copies the profile, and moves the IPC socket

Driving someone else's Electron application requires isolation, and these variables describe the isolation. CODEX_WEB_OFFICIAL_BUNDLE_DIR, default .data/cache/codex-official-bundle, is the cache directory for the unpacked official bundle. CODEX_WEB_OFFICIAL_USER_DATA_DIR, default .data/official-user-data, is a separate Electron profile directory, so the browser session is not the desktop app's own profile. CODEX_WEB_OFFICIAL_TMPDIR and its alias CODEX_WEB_OFFICIAL_TMP_DIR generate a temporary directory for the official hidden runtime, described as the place that keeps the official IPC socket isolated. CODEX_WEB_OFFICIAL_AUTO_SCAN_UPGRADE defaults to 1, which means the official Codex runtime is rescanned for updates at every start; set it to 0 and the existing cache is preferred, scanning only when that cache is missing or unusable. The gateway's own working directory is separate again, .data/runtime by default, diagnostics go to .data/reports, and CODEX_HOME still points at ~/.codex for the Codex CLI and app-server. The gateway test list in package.json names this area directly: official-desktop-compat, official-runtime, official-electron-module-hook, compatibility-registry, compatibility-service, and loopback-host.

Thirteen rows of the advanced table only move a log threshold

The advanced debugging table is not about features. CODEX_WEB_SLOW_LOG_MS sets the IPC slow call threshold at 750 milliseconds. The WebSocket side carries its own set of limits: OPENCODEX_WS_SEND_SLOW_MS at 80, OPENCODEX_WS_STRINGIFY_SLOW_MS at 20, OPENCODEX_WS_BUFFERED_LOG_BYTES at 524288, and OPENCODEX_WS_LARGE_LOG_BYTES at 262144. The app-host channel adds OPENCODEX_APP_HOST_TRAFFIC_FLUSH_MS at 2000 and OPENCODEX_APP_HOST_LARGE_FRAME_BYTES at 65536, with OPENCODEX_DEBUG_WS turning on WebSocket and app-host link diagnostics. Four more decide whether bytes get compressed at all: OPENCODEX_WS_DISABLE_DEFLATE, a 65536 threshold, a concurrency of 4, and zlib level 3. Local files are bounded too, at most 20 picked files per web request, 52428800 bytes per file, 104857600 bytes in total, held for 86400000 milliseconds before the temporary directory is reclaimed. On disk, OPENCODEX_LOG_MAX_MB caps gateway.log at 10 MB and keeps one gateway.log.old beside it. Two final switches, CODEX_WEB_DISABLE_ASSET_CACHE and CODEX_WEB_DISABLE_GZIP, turn off static asset caching and response compression.

Windows gets the app-server and CLI path overrides, Linux does not

When the automatic scan cannot find what it expects, four overrides exist. CODEX_DESKTOP_APP_PATH takes the install path or the location of app.asar. CODEX_DESKTOP_EXECUTABLE_PATH takes the Electron executable, and that row names Windows and Linux. CODEX_APP_SERVER_BINARY_PATH takes the Codex app-server or CLI executable, and CODEX_CLI_PATH takes the Codex CLI executable; both of those rows name Windows only. Linux is listed as a supported system with no prebuilt launcher, which leaves it without documented overrides for the two server-side binaries even though the Electron executable path is offered. The rest of the configuration reads as platform neutral. OPENCODEX_PREFERRED_LANGUAGES defaults to zh-CN and accepts a JSON array such as ["zh-Hans-CN","en-CN"], and the launcher passes the system preference automatically. OPENCODEX_PLUGIN_DIRS is empty by default and expects external plugin roots whose structure matches web-shell/plugins, with several directories given either as a JSON array or separated by the system path separator. Plugin development is documented separately at docs/PLUGINS.md, and examples/plugin-v2-hello sits in the tree as a starting point.

Two session stores, and a five minute window on file previews

The rough edges named here are specific. If OpenCodex and the official desktop run side by side, both maintain their own session state, so the same data is not necessarily synchronized in real time; the suggested fix is to use only OpenCodex, locally or remotely, optionally with PWA. A first load of session history can be slow, and slower again over a remote LAN, with a refresh or a re-entry as the stated remedy. Access tokens and file tokens live on very different clocks: CODEX_WEB_AUTH_TOKEN_TTL_MS defaults to 43200000, which is 12 hours, while CODEX_WEB_LOCAL_FILE_TOKEN_TTL_MS defaults to 300000, which is 5 minutes, so a local file preview URL stops working quickly. Remote reach is not solved inside this repository. It states that OpenCodex itself provides no remote access service, asks for Tailscale, ZeroTier, Cloudflare Tunnel, or a company VPN to build the path, and tells you to turn on LAN mode in the launcher afterwards, while recommending against putting OpenCodex on the public internet directly. The front page here is the Chinese edition, with an English edition linked at docs/README_EN.md.

Editorial conclusion

Check the bind address and the password before this reaches a network you do not control, because the command line path starts on HOST 0.0.0.0 with PORT 3737 and the password is a separate later step. Use it if you want a terminal, a file tree, and review panes on a phone over Tailscale, ZeroTier, or a company VPN, and you already have Codex Desktop or ChatGPT Desktop on the machine. Skip it if you only need a handful of chats, or if you cannot accept a layer that unpacks and hooks an official desktop runtime which rescans itself for updates on every start. Before relying on it, read the version you actually installed: package.json reports 2.1.0 and tag v2.1.0 is dated 2026-09-13, while the same description field still frames the project as middleware for Codex Desktop only.

Frequently asked questions

What is OpenCodex and what does it need installed before it will run?

OpenCodex is a middleware layer that exposes an installed Codex Desktop, or the newer ChatGPT Desktop, to a browser on a phone, tablet, or another computer. It needs Node, pnpm, and one of those desktop apps already present on the machine, though that app does not have to be running.

Does OpenCodex need an access password before it can be reached over a network?

The launcher can set an access password through its visual settings, and config.yaml holds an auth password block for the command line gateway. The two entry points do not start equally exposed: the gateway defaults to HOST 0.0.0.0 and PORT 3737, while the launcher defaults to OPENCODEX_HOST 127.0.0.1 and a random available port.

How do I install OpenCodex on Linux?

There is no prebuilt launcher for Linux, and the front page sends Linux users to the command line path and docs/LINUX_GUIDE.md. macOS and Windows get packaged installers through launcher:dist:mac and launcher:dist:win, while Linux is listed among the supported systems only with a command line start.

Can OpenCodex be reached from outside the local network without exposing it publicly?

The project states that OpenCodex provides no remote access service of its own. It asks you to build the network path with Tailscale, ZeroTier, Cloudflare Tunnel, or a company VPN and then open LAN mode in the launcher, and it recommends against exposing OpenCodex to the public internet directly.

Does OpenCodex stay in sync if I also use the official Codex or ChatGPT Desktop?

Both keep their own session state, so the same data is not necessarily synchronized in real time when they run side by side. The recommendation is to use only OpenCodex, locally or remotely, and to pair it with PWA if a desktop-like feel is wanted.

Official sources

  1. Issues
  2. License: AGPL-3.0
  3. README
  4. Releases
  5. RyensX/OpenCodex on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/ryensx-opencodex.svg)](https://hysenlabs.com/projects/ryensx-opencodex)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/ryensx-opencodex.svg)](https://hysenlabs.com/projects/ryensx-opencodex)

Was this useful?