Codex macOS to Linux Port

Port script that runs the official Codex Desktop App (macOS-only) on x86_64 Linux.

Tested on EndeavourOS (Arch-based), Kernel 6.18.7, Electron 39.5.2, Codex CLI 0.101.0.

Based on New-Codex-App-Manjaro-Arch-Port by fvaha, which did not work on my system due to isPackaged checks and pnpm symlink issues.

What it does

Step	Description
0/10	System check -- detects OS, architecture, available tools
1/10	Install system packages via detected package manager
2/10	Ensure pnpm, asar, and Electron are available
3/10	Check Codex.dmg update via ETag/SHA-256, download only when changed
4/10	Extract DMG, unpack app.asar (with HFS partition fallback)
5/10	Recompile native modules (better-sqlite3, node-pty) for Linux/Electron
6/10	Patch JS bundle -- neutralize isPackaged guards, inject build metadata
7/10	Resolve all symlinks, repack app as .asar (app.isPackaged = true)
8/10	Create launcher script run-codex.sh and .desktop entry
9/10	Install @openai/codex CLI globally via pnpm
10/10	Clean up temp files, print summary

Problems solved

Error	Cause	Fix
better-sqlite3 is only bundled with the Electron app	App checks app.isPackaged, which is false in directory mode	Patch JS throws + repack as .asar
ENOENT: stat .../better-sqlite3 during asar pack	pnpm stores modules as symlinks; cp -a copies the link, not the target	cp -aL (dereference) + resolve all symlinks before packing
Ignored build scripts (pnpm 10+)	pnpm 10 blocks postinstall scripts by default	Set pnpm.onlyBuiltDependencies in isolated build project
Missing codexBuildFlavor / CodexBuildNumber	Build metadata absent from package.json	Injected automatically
Arch: p7zip vs 7zip package name	Package renamed in newer Arch repos	Auto-detection

Supported distributions

Package manager	Distributions
pacman	Arch, Manjaro, EndeavourOS, Garuda
apt	Debian, Ubuntu, Linux Mint, Pop!_OS
dnf	Fedora, RHEL 8+, CentOS Stream, Rocky, Alma
yum	CentOS 7, RHEL 7, Amazon Linux
zypper	openSUSE Leap, Tumbleweed
apk	Alpine Linux
xbps	Void Linux
portage	Gentoo
nix-env	NixOS

Requirements

• x86_64 architecture (aarch64 experimental)
• One of the package managers listed above
• Internet access
• OpenAI account

Usage

git clone https://github.com/YOUR_USER/codex-linux-port.git
cd codex-linux-port
chmod +x port.sh
./port.sh

The script prompts for sudo to install system packages. Everything else runs automatically.

After completion:

~/apps/codex-port/run-codex.sh

Or search for "Codex" in your application menu.

Environment variables

Variable	Default	Description
CODEX_CLI_PATH	~/.local/share/pnpm/codex	Path to Codex CLI binary
CODEX_ELECTRON_ARGS	--no-sandbox	Electron flags passed to the launcher
PNPM_HOME	~/.local/share/pnpm	pnpm global install directory

Directory layout after install

~/apps/codex-port/
    app.asar                    # packed app (Electron loads this)
    app.asar.unpacked/          # native .node modules referenced by asar
        node_modules/
            better-sqlite3/build/Release/better_sqlite3.node
            node-pty/bin/linux-x64-140/node-pty.node
    app_asar/                   # unpacked app (backup / fallback)
    dmg_extracted/              # raw DMG contents
    run-codex.sh                # launcher

~/Downloads/codex-macos/
    Codex.dmg

~/.local/share/applications/
    codex.desktop

~/.local/share/pnpm/
    codex                       # CLI binary (global)

FAQ

Failed to register codex:// protocol handler -- Harmless. Custom URL schemes cannot be registered this way on Linux. The app works fine without it.

ENOENT: path does not exist: ...extcloud/... -- Stale workspace paths from a previous session. The app logs the error and continues normally.

[worker-manager] Worker exited code=1 -- Happens on normal shutdown (EPIPE when the pipe to the CLI process closes). Not an error.

Can I re-run the script? -- Yes. It is idempotent. The DMG is checked via ETag/SHA-256 metadata and re-downloaded only when changed; packages are not reinstalled; the app is re-extracted and re-patched when a new DMG is detected.

Uninstall

rm -rf ~/apps/codex-port
rm -rf ~/Downloads/codex-macos
rm -f ~/.local/share/applications/codex.desktop
pnpm rm -g @openai/codex

pnpm PATH setup

If codex is not found after installation, add to your shell config:

# ~/.bashrc or ~/.zshrc
export PNPM_HOME="$HOME/.local/share/pnpm"
export PATH="$PNPM_HOME:$PATH"

# ~/.config/fish/config.fish
set -gx PNPM_HOME $HOME/.local/share/pnpm
fish_add_path $PNPM_HOME

License

This script is provided as-is. The Codex Desktop App is property of OpenAI. This project is not officially supported or endorsed by OpenAI.

Attribution

Original port concept: fvaha/New-Codex-App-Manjaro-Arch-Port