Codex Desktop for Linux

Run OpenAI Codex Desktop on Linux.

The official Codex Desktop app is macOS-only. This project provides an automated installer that converts the macOS .dmg into a working Linux application.

How it works

The installer:

1. Extracts the macOS .dmg (using 7z)
2. Extracts app.asar (the Electron app bundle)
3. Rebuilds native Node.js modules (node-pty, better-sqlite3) for Linux
4. Removes macOS-only modules (sparkle auto-updater)
5. Downloads Linux Electron (same version as the app — v40)
6. Repacks everything and creates a launch script

Prerequisites

Node.js 20+, npm, Rust/Cargo, 7z, curl, and build tools (gcc/g++/make).

Debian/Ubuntu

sudo apt install nodejs npm cargo rustc p7zip-full curl build-essential

Fedora

sudo dnf install nodejs npm cargo rust p7zip curl
sudo dnf groupinstall 'Development Tools'

Arch

sudo pacman -S nodejs npm cargo rust p7zip curl base-devel

You also need the Codex CLI:

npm i -g @openai/codex

Installation

Option A: Auto-download DMG

git clone https://github.com/ilysenko/codex-desktop-linux.git
cd codex-desktop-linux
chmod +x install.sh
./install.sh

Option B: Provide your own DMG

Download Codex.dmg from openai.com/codex, then:

./install.sh /path/to/Codex.dmg

Usage

The app is installed into codex-app/ next to the install script:

codex-desktop-linux/codex-app/start.sh

Or add an alias to your shell:

echo 'alias codex-desktop="~/codex-desktop-linux/codex-app/start.sh"' >> ~/.bashrc

Custom install directory

CODEX_INSTALL_DIR=/opt/codex ./install.sh

How it works (technical details)

The macOS Codex app is an Electron application. The core code (app.asar) is platform-independent JavaScript, but it bundles:

• Native modules compiled for macOS (node-pty for terminal emulation, better-sqlite3 for local storage, sparkle for auto-updates)
• Electron binary for macOS

The installer replaces the macOS Electron with a Linux build and recompiles the native modules using @electron/rebuild. The sparkle module (macOS-only auto-updater) is removed since it has no Linux equivalent.

The Riff fork replaces the upstream Python http.server workaround with a small Rust launcher that:

• serves extracted webview assets from an embedded local HTTP server
• binds 127.0.0.1:5175 for compatibility with the current extracted app
• resolves the Codex CLI path before launch
• supervises Electron process startup from a single runtime entrypoint

Troubleshooting

Problem	Solution
Error: write EPIPE	Update to the launcher that logs Electron output to codex-desktop-linux.log instead of inheriting a broken stdio pipe
Blank window	Check that the Rust launcher started cleanly and that content/webview/ was extracted
CODEX_CLI_PATH error	Install CLI: npm i -g @openai/codex
GPU/rendering issues	Try: ./codex-app/start.sh --disable-gpu
Sandbox errors	Check whether your Linux environment supports Electron sandboxing cleanly

Disclaimer

This is an unofficial community project. Codex Desktop is a product of OpenAI. This tool does not redistribute any OpenAI software — it automates the conversion process that users perform on their own copies.

License

MIT