Unofficial Flatpak packaging scripts for the OpenAI Codex desktop app on Linux ARM64 (aarch64).
This is not an official OpenAI release. It extracts the macOS .dmg, swaps in the Linux binaries, rebuilds native Node modules, and packages everything as a Flatpak.
Tested on Fedora 44 (aarch64) running on Snapdragon X (PocketBlue) hardware.
Install once on your system:
# Tools
sudo dnf install -y p7zip-plugins nodejs npm flatpak-builder
# Flatpak runtimes (from Flathub)
flatpak install flathub org.freedesktop.Platform//25.08
flatpak install flathub org.freedesktop.Sdk//25.08Toolbox users: run
flatpak-builderfrom within your toolbox container. Add--disable-rofiles-fuseif FUSE is unavailable (it is passed automatically bybuild.sh).
- Download the macOS
Codex.dmg(Apple Silicon) from openai.com/codex - Run:
git clone https://github.com/tompta1/codex-linux-flatpak
cd codex-linux-flatpak
./build.sh /path/to/Codex.dmg- Launch:
flatpak run com.openai.Codex
# or from a toolbox container:
flatpak-spawn --host flatpak run com.openai.CodexThe app also appears in your desktop application launcher.
| Step | Action |
|---|---|
| 1 | Extracts Codex.app from the DMG using 7z |
| 2 | Detects the bundled Electron version from the app's framework plist |
| 3 | Downloads Electron linux-arm64 from GitHub releases |
| 4 | Downloads the codex-rs CLI linux-arm64 binary from openai/codex releases |
| 5 | Copies app.asar (the JS/web frontend — architecture-neutral) |
| 6 | Rebuilds better-sqlite3 and node-pty native modules for Electron/linux-arm64 using @electron/rebuild |
| 7 | Extracts 256×256 and 512×512 icons from the .icns bundle |
| 8 | Runs flatpak-builder --user --install |
These are the non-obvious issues discovered when porting the macOS app to Linux:
The app checks app.isPackaged to decide how to load the renderer. When running electron app.asar directly, isPackaged is false, so it tries a local Vite dev server that doesn't exist.
Fix: Set ELECTRON_RENDERER_URL=file:///path/to/app.asar/webview/index.html.
The app has this override built in: Kh() { return process.env.ELECTRON_RENDERER_URL || 'http://localhost:5175/' }.
better-sqlite3 and node-pty ship as compiled macOS ARM64 bundles in the app. They must be recompiled for the target Electron version and linux/arm64.
Fix: @electron/rebuild --version <N> --arch arm64.
Electron on GNOME/mutter logs wayland_frame_manager.cc: The server has buggy presentation feedback repeatedly. This is a Wayland compositor timing quirk — cosmetic only.
Fix: Inside Flatpak, Electron uses Wayland natively and this is suppressed via --log-level=3. For direct launch outside Flatpak, add --ozone-platform=x11 to use XWayland instead.
The 142 MB codex binary bundled in Resources/ is the Rust backend (codex-rs), compiled for macOS. It must be replaced with the Linux build.
Fix: Download the aarch64-unknown-linux-gnu binary from the openai/codex releases.
flatpak-builder uses FUSE overlays during build. FUSE is restricted in toolbox/container environments.
Fix: flatpak-builder --disable-rofiles-fuse.
When OpenAI releases a new Codex.dmg:
./build.sh /path/to/NewCodex.dmgThe script auto-detects the Electron version from the new bundle and downloads matching binaries.
| Permission | Reason |
|---|---|
--filesystem=home |
Read/write project files |
--share=network |
OpenAI API access |
--socket=wayland + --socket=fallback-x11 |
Display |
--device=dri |
GPU acceleration |
--allow=devel |
Electron requires relaxed seccomp |
This project is not affiliated with or endorsed by OpenAI. The Codex desktop app is proprietary software — this repo contains only build scripts and packaging metadata. You must obtain the macOS .dmg directly from OpenAI.