codex-app-linux

Run the Codex desktop app on Linux via npm.

codex-app-linux is a thin launcher:

• expects codex CLI to already be installed
• downloads the matching Linux desktop binary archive on first run
• launches the desktop app with CODEX_CLI_PATH wired up

Quick Start

aur

• Latest

  yay -S codex-app-unofficial

• Beta

  yay -S codex-app-beta-unofficial

npm

• Install globally

  npm i -g codex-app-linux@latest

  npm i -g codex-app-linux@beta

• Run once with npx:

  npx codex-app-linux@latest

  npx codex-app-linux@beta

• Browser mode from npm (note: many features are missing, don't expect much):

  npx codex-app-linux web --open

• Disable browser auth entirely (unsafe; only behind a trusted reverse proxy / tailnet):

  npx codex-app-linux web --dangerously-disable-auth true

Requirements

• Linux x64
• codex on PATH
• GitHub access not required for normal app launch

If CODEX_CLI_PATH is already set, the launcher uses it. Otherwise it falls back to which codex.

What This Repo Does

This repo builds and publishes the Linux release pipeline for Codex desktop:

• tracks upstream prod and beta appcast feeds
• rebuilds the upstream app for Linux x64
• emits linux-unpacked and AppImage
• publishes codex-app-linux on npm

Repo Commands

npm test
npm run release:prod
npm run release:beta

Distribution Model

GitHub Releases:

• source of truth for Linux desktop artifacts
• uploads AppImage
• uploads a tarball of linux-unpacked

npm:

• publishes codex-app-linux
• acts as a thin launcher
• downloads the matching linux-unpacked tarball from GitHub Releases on first run

AUR:

• publishes binary packages from the same GitHub release tarballs
• installs the unpacked app into /opt
• installs desktop entry + icon for Arch launchers/menus
• prod package: codex-app-unofficial
• beta package: codex-app-beta-unofficial

Launcher behavior:

• uses existing CODEX_CLI_PATH if set
• otherwise sets CODEX_CLI_PATH from which codex
• errors if neither is available
• extracts linux-unpacked into cache on first run
• npm launches the unpacked binary directly
• npm also exposes codex-app-linux web to serve the bundled UI in a browser
• browser auth can be disabled explicitly with --dangerously-disable-auth true
• AppImage and linux-unpacked release binaries also perform the same codex lookup at launch
• browser mode is npm-only; AUR packages continue to ship desktop launch behavior only

GitHub Actions

Workflow: .github/workflows/release.yml

• scheduled 7 times daily
• checks both upstream channels
• builds linux-unpacked and AppImage
• creates/releases tagged GitHub assets
• publishes latest for prod, beta for beta

Nix

This repo also includes a flake.nix with:

• devShells.default for local release work
• apps.release-prod for nix run .#release-prod
• apps.release-beta for nix run .#release-beta