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.

Tested Arch Linux Setup

This is the setup I use on Arch Linux with Hyprland:

• Codex CLI installed globally with Bun
• official macOS DMG extracted into the ignored local work/ directory
• matching Electron and native modules rebuilt locally
• Chromium sandbox enabled, with the cleaner launch profile on by default
• ~/.local/bin/lin-codex launcher plus a desktop entry and codex:// handler

The DMG, extracted application, login state, conversations, and personal Codex configuration stay local and are never committed.

Prerequisites

• Linux (x86_64)
• Bun (for installing the Codex CLI)
• 7z (p7zip-full on Debian/Ubuntu, p7zip on Arch)
• Electron (the version declared by the Codex app, 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

Cleaner Launch Mode (fewer background helpers)

run.sh now defaults to a cleaner profile that disables non-essential Chromium background services.

Useful toggles:

# default: cleaner mode enabled
./run.sh

# disable cleaner mode (full default Chromium behavior)
CODEX_LINUX_CLEAN_MODE=0 ./run.sh

# reduce helper process count further by disabling GPU process
CODEX_DISABLE_GPU=1 ./run.sh

Chromium's sandbox stays enabled by default. If Electron cannot initialize it on your distribution, use CODEX_DISABLE_SANDBOX=1 ./run.sh only as a temporary compatibility fallback. Disabling the sandbox weakens renderer isolation.

Updating to a New Codex Build

Download a fresh Codex.dmg, replace the old one, then run:

chmod +x update.sh
./update.sh

Or pass a custom DMG path:

./update.sh /path/to/Codex.dmg

How It Works

1. setup.sh extracts the macOS DMG using 7z, reads the required Electron version from the app metadata, 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 setup script patches the app entry point declared in package.json, so hashed or renamed upstream entry files continue to work
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
├── update.sh         # Rebuild from a new DMG with rollback on failure
├── install-app.sh    # Install the user launcher and desktop entry
├── 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.

Your Codex authentication, conversations, and ~/.codex/config.toml remain outside this repository. Do not copy those files into a public clone because they can contain credentials, private project paths, and personal settings.

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