Lin-Codex

Run the OpenAI Codex desktop app on Linux using the official macOS installer.

No official Linux build exists — this project extracts the macOS Electron app, rebuilds native modules for Linux, and launches it. No binaries are shipped; you supply your own Codex installer.

Inspiration taken from Win-Codex by @JDhruv14.

Prerequisites

• Linux (x86_64)
• Bun (for installing the Codex CLI)
• 7z (p7zip-full on Debian/Ubuntu, p7zip on Arch)
• Electron 40 (installed automatically by setup)
• OpenAI Codex CLI: bun install -g @openai/codex

Quick Start

# 1. Clone the repo
git clone https://github.com/satvikxs/Linux-codex.git
cd Linux-codex

# 2. Download the latest Codex macOS DMG from https://openai.com/codex
#    and place it in the repo root as Codex.dmg

# 3. Run setup (extracts DMG, installs Electron, rebuilds native modules)
chmod +x setup.sh
./setup.sh

# 4. Launch Codex
chmod +x run.sh
./run.sh

# 5. Install desktop app entry (shows in wofi/rofi and app menus)
chmod +x install-app.sh
./install-app.sh

How It Works

1. setup.sh extracts the macOS DMG using 7z, installs Electron 40 locally, and rebuilds native modules (better-sqlite3, node-pty) for Linux
2. run.sh sets the required environment variables and launches the Electron app with a Linux-compatible shim
3. The shimmed main.js (already inside the extracted app) patches paths so the macOS-targeted renderer runs on Linux
4. install-app.sh creates a user launcher (~/.local/bin/lin-codex) and desktop entry (~/.local/share/applications/lin-codex.desktop)

Project Structure

Lin-codex/
├── setup.sh          # One-time setup: extract DMG + rebuild natives
├── run.sh            # Launch the Codex app
├── Codex.dmg         # You supply this (not included)
├── LICENSE
├── README.md
└── work/             # Generated by setup.sh (gitignored)
    ├── extracted/    # Raw DMG contents
    ├── app/          # Electron app with Linux shim
    └── native/       # Electron + rebuilt native modules

What's NOT Included

This repo ships zero binaries. You need to:

• Download the Codex macOS DMG yourself from openai.com/codex
• Install the Codex CLI separately (bun install -g @openai/codex)

Do not redistribute the Codex DMG or OpenAI binaries.

Contributing

Issues and PRs are welcome and appreciated! If you run into problems or have improvements, please open an issue or submit a pull request.

This is a community project — I'll actively review and fix issues.

Desktop App Integration (Arch/Hyprland)

To make Codex appear like a normal app in your launcher:

chmod +x install-app.sh
./install-app.sh

This installs:

• ~/.local/bin/lin-codex (launcher)
• ~/.local/share/applications/lin-codex.desktop (desktop entry)

Then search for Codex in wofi/rofi.
If it doesn't show immediately, restart your launcher or log out/in.

Windows Users

Looking for Windows support? Check out Win-Codex by @JDhruv14.

Troubleshooting

better-sqlite3 / NODE_MODULE_VERSION mismatch

If launch fails with an error like:

• was compiled against a different Node.js version
• NODE_MODULE_VERSION 137 vs 143 (or any mismatch)

clean the generated build artifacts and run setup again so native modules are rebuilt for your Electron runtime:

rm -rf work/native work/app
./setup.sh
./run.sh

Disclaimer

This is not an official OpenAI project. It is an unofficial community effort to run the Codex desktop app on Linux.

License

MIT