Codex App Flatpak for Linux

Community Flatpak packaging scripts for the Codex desktop app on Linux.

This project takes the macOS .dmg, swaps in Linux binaries, patches a few desktop-specific issues, rebuilds native Node modules, and produces a runnable Flatpak for:

• x86_64 / amd64
• aarch64 / arm64

The repository tracks only scripts and packaging metadata. Generated artifacts such as app.asar, Electron binaries, rebuilt native modules, icons, and build output are intentionally ignored by git.

Prerequisites

Install once on Ubuntu:

sudo apt update
sudo apt install -y build-essential p7zip-full unzip curl tar nodejs npm python3 flatpak-builder

flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install -y flathub org.freedesktop.Platform//25.08
flatpak install -y flathub org.freedesktop.Sdk//25.08

Build

1. Download the official Codex.dmg.
2. Run:

./build.sh /path/to/Codex.dmg

3. Launch:

flatpak run com.openai.Codex

What The Build Script Does

build.sh performs the full Linux packaging flow:

1. Extracts Codex.app from the .dmg
2. Detects the host architecture
3. Downloads matching Linux Electron and codex-rs
4. Patches the packaged app bundle for Linux-specific issues
5. Rebuilds better-sqlite3 and node-pty
6. Preserves the upstream app.asar / app.asar.unpacked layout for native modules
7. Extracts icons
8. Builds and installs the Flatpak locally

Linux-Specific Patches

The build applies a small patch set to the packaged app bundle via scripts/patch-app-bundle.py:

• Replaces the transparent Linux window background with an opaque one to avoid rendering artifacts
• Guards Electron send() calls during shutdown so destroyed windows do not throw noisy errors

Runtime packaging also includes:

• A launcher script in flatpak-sources/codex-launcher.sh
• A host git wrapper in flatpak-sources/git-wrapper.sh, so the app can query git state from inside the Flatpak sandbox

Native Modules

The desktop app depends on native Node modules such as better-sqlite3 and node-pty.

For Linux builds, the packaging step must keep the same split used by the upstream app:

• JavaScript stays in app.asar
• Native module payloads stay in app.asar.unpacked

If those native files are accidentally packed back into app.asar, Electron may fail during startup with an error similar to:

/tmp/org.chromium.Chromium.*/invalid ELF header

That usually means the asar repack step no longer preserves the upstream unpacked layout.

Distribute To Other Ubuntu Machines

You have two practical options.

Option 1: Single .flatpak Bundle

Create a standalone bundle:

./make-bundle.sh

By default this writes:

dist/codex-community-<arch>.flatpak

Install it on another Ubuntu machine:

sudo apt update
sudo apt install -y flatpak
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install --user ./codex-community-x86_64.flatpak
flatpak run com.openai.Codex

Option 2: Host Your Own Flatpak Repo

Create or refresh a local Flatpak repo:

./make-repo.sh

This writes metadata into:

repo/

Host that directory over HTTPS, then on another Ubuntu machine:

sudo apt update
sudo apt install -y flatpak
flatpak remote-add --user --if-not-exists codex-community https://your-domain.example/repo
flatpak install --user codex-community com.openai.Codex
flatpak update --user com.openai.Codex

Updating To A New DMG

When a new desktop build appears:

./build.sh /path/to/NewCodex.dmg

Then recreate the bundle or repo:

./make-bundle.sh
# or
./make-repo.sh

Repository Layout

• build.sh: full Linux packaging flow
• make-bundle.sh: export a single-file Flatpak bundle
• make-repo.sh: export a reusable Flatpak repo
• com.openai.Codex.yml: Flatpak manifest
• flatpak-sources/: static packaging files kept in git
• scripts/patch-app-bundle.py: bundle patch logic

Notes

• flatpak-sources/app.asar, flatpak-sources/app.asar.unpacked, flatpak-sources/electron, flatpak-sources/codex-cli, and extracted icons are generated files
• build-dir/, .flatpak-builder/, repo/, and dist/ are build outputs
• If a future Codex update changes the minified Electron bundle structure, the patch script may need to be updated