Codex App for Linux

Run OpenAI Codex on Linux.

The official Codex app is published for macOS. This project adapts the upstream Codex.dmg into a Linux Electron app, then gives you a few practical ways to run it: directly from a checkout, through a native package, or through the Nix flake.

Note

This is an unofficial community project. It does not redistribute OpenAI software; it automates a local conversion from the upstream Codex DMG.

Who This Is For

• Linux users who want the Codex app on their workstation.
• Packagers who want .deb, .rpm, or pacman artifacts built from a local app tree.
• NixOS users who want the flake path and Electron patching handled for them.
• Maintainers and agents who need the deeper packaging, updater, and policy references outside the README.

Quick Start

git clone https://github.com/nisavid/codex-app-linux.git
cd codex-app-linux
bash scripts/install-deps.sh
make build-app
make run-app

scripts/install-deps.sh supports Debian/Ubuntu, Fedora, openSUSE, and Arch Linux hosts. On openSUSE it uses non-interactive zypper to install nodejs-default, npm-default, python3, p7zip-full, curl, unzip, and the devel_basis pattern.

make build-app downloads or reuses Codex.dmg, extracts the app, patches the macOS bundle for Linux, rebuilds native modules, downloads a Linux Electron runtime, and writes codex-app/start.sh.

On first launch, the app can install the Codex CLI if it is missing and npm is available. To install the CLI yourself:

npm i -g @openai/codex

If global npm installs require elevated privileges on your system, use a rootless prefix instead:

npm i -g --prefix ~/.local @openai/codex

To build from a DMG you already downloaded:

make build-app DMG=/path/to/Codex.dmg

Build A Native Package

Native package builders repackage the generated app tree. Run make build-app first so codex-app/ exists.

Build the package format that matches the current host:

make package

Or choose a format directly:

make deb
make rpm
make pacman

For a fresh package build, start by removing the generated app tree, cached DMG, and old package outputs:

make clean build-app package

That rebuilds codex-app/ from the current upstream DMG source, then builds the native package format for your host. To choose a package format explicitly, replace package with deb, rpm, or pacman.

Package outputs land in dist/:

Target	Output
Debian	dist/codex-app_<upstream-version>_amd64.deb
RPM / Fedora / openSUSE	dist/codex-app-<upstream-version>-1.x86_64.rpm
Arch Linux	dist/codex-app-<upstream-version>-1-x86_64.pkg.tar.zst

The package version comes from the upstream Codex app bundle. For example, 26.422.30944 (2080) becomes 26.422.30944.2080.

Native packages are named codex-app. They declare replacement metadata for the older codex-desktop package name where the package format supports it. The installed launcher is /usr/bin/codex-app, and the app lives under /opt/codex-app.

Before publishing packages, run the release gate with a trusted upstream DMG hash. Set CODEX_RELEASE_GPG_KEY to produce detached signatures, and set REQUIRE_RELEASE_SIGNATURE=1 when public releases must fail without them:

CODEX_DMG_SHA256=<reviewed-dmg-sha256> \
REQUIRE_RELEASE_SIGNATURE=1 \
CODEX_RELEASE_GPG_KEY=<key-id-or-email> \
make release-gate

For a local signed rehearsal where signatures are optional, omit REQUIRE_RELEASE_SIGNATURE=1 and keep CODEX_RELEASE_GPG_KEY set.

The gate verifies the DMG hash, scans the generated app for high-confidence Electron security anti-patterns, validates package metadata, writes dist/SHA256SUMS. When CODEX_RELEASE_GPG_KEY is set, it also writes dist/SHA256SUMS.asc, exports dist/release-signing-key.asc, and verifies the detached signature against that public key in a temporary keyring. Unsigned rehearsal runs omit those signature artifacts unless REQUIRE_RELEASE_SIGNATURE=1 is set.

Install the newest package in dist/:

make install

NixOS

The flake handles dependencies and Electron patching:

nix run github:nisavid/codex-app-linux

This installs the generated app into codex-app/ in the current directory. For a development shell:

nix develop github:nisavid/codex-app-linux

If nix run reports a fixed-output hash mismatch, the upstream DMG was likely republished after the pinned hash changed. A scheduled GitHub Actions job refreshes that hash on main once every 24 hours. Retry after the bot has had time to run; if it still fails, open an issue.

Updates

Native packages install codex-app-updater, a systemd --user service that checks for newer upstream DMGs, rebuilds the matching Linux package locally, and uses pkexec only for the final package install step.

Useful service commands after installing a native package:

make service-enable
make service-status
codex-app-updater status --json

The packaged launcher also starts the user service on a best-effort basis when you open the app.

Troubleshooting

Start with the launcher log:

sed -n '1,160p' ~/.cache/codex-app/launcher.log

Common next steps:

• blank window or splash hang: check whether something else is serving port 5175;
• Codex CLI warning: install @openai/codex globally or under ~/.local;
• stale app tree: rebuild with ./install.sh --fresh;
• updater service issue: inspect ~/.local/state/codex-app-updater/service.log.

See Troubleshooting for the full symptom table and log locations.

Learn More

Goal	Go here
Build, run, package, or install the app	Build and Run Guide
Diagnose launch, CLI, webview, or updater issues	Troubleshooting
Browse all repo docs by role and task	Documentation Index
Follow release notes	Changelog
Try the experimental rootless install path	User-Local Desktop Integration
Maintain packaging, launcher, or updater behavior	Package and Runtime Maintenance

For contributors and maintenance agents, start with AGENTS.md. It is the always-loaded policy surface; detailed recipes and validation matrices live in the docs linked above.