Codex Desktop for Linux

June 11, 2026 · View on GitHub

Unofficial Linux build wrapper for OpenAI Codex Desktop. The official Codex app is available for macOS and Windows; this repository covers Linux by converting the upstream macOS Codex.dmg into a runnable Linux Electron app.

The project builds native .deb, .rpm, and .pkg.tar.zst packages, supports local AppImage self-builds and Nix, and can install a local update manager that rebuilds future Linux packages from newer upstream DMGs.

Before opening a pull request, read CONTRIBUTING.md. For implementation details, see AGENTS.md.

Install By Platform

Platform	Recommended path	Notes
Debian, Ubuntu, Pop!_OS, Mint, Elementary	`make bootstrap-native`	Builds and installs a `.deb`
Fedora	`make bootstrap-native`	Builds and installs an `.rpm`
openSUSE	`make bootstrap-native`	Builds and installs an `.rpm`
Arch, Manjaro, EndeavourOS	`make bootstrap-native`	Builds and installs a pacman package
NixOS / Nix	`nix run github:ilysenko/codex-desktop-linux`	See Nix docs
Atomic desktops / other distros	`make build-app && make appimage`	Local self-build; no bundled updater

Native install:

git clone https://github.com/ilysenko/codex-desktop-linux.git
cd codex-desktop-linux
make bootstrap-native

If dependencies are already installed:

make install-native

make bootstrap-native installs build dependencies, downloads a fresh upstream Codex.dmg, builds codex-app/, packages it for your distro, and installs the newest artifact from dist/.

If you are installing dependencies manually on Fedora:

# Fedora 41+
sudo dnf install python3 7zip curl unzip rpm-build @development-tools

# Fedora < 41
sudo dnf install python3 p7zip p7zip-plugins curl unzip rpm-build
sudo dnf groupinstall 'Development Tools'

For a guided first-run checklist and optional feature picker:

make setup-native

See Native setup for the wizard, non-interactive feature selection, cleanup flow, and PACKAGE_WITH_UPDATER=0.

Before You Install

The generated app and native packages bundle a managed Linux Node.js runtime. You do not need a distro nodejs / npm package for normal installs, Browser Use, Codex CLI install/update, or local auto-update rebuilds.

The Codex CLI is still required at runtime. The first launch can install or update @openai/codex with the bundled npm, or you can manage the CLI yourself.

X11 and Wayland sessions are supported. The launcher prefers XWayland on Wayland when available for better Electron popup positioning, then falls back to Electron's automatic Wayland handling. See Troubleshooting for GPU, Vulkan, and /tmp noexec workarounds.

Feature Matrix

Feature	Default	Enable / use	Docs
Standard Codex Desktop UI	Always	Install or run the generated app	This README
Managed Linux Node.js runtime	Always	Bundled during build/install	Build and packaging
Native packages	Always	`make package && make install`	Build and packaging
Auto-update manager	Native packages	Included unless `PACKAGE_WITH_UPDATER=0`	Updater
AppImage self-build	Manual	`make build-app && make appimage`	Build and packaging
Nix flake	Manual	`nix run github:ilysenko/codex-desktop-linux`	Nix
GUI install prompts	If installed	Uses `kdialog` / `zenity`, then terminal fallback	Native setup
Linux file manager integration	Always	Built into core Linux patches	Architecture
Chrome plugin native host	Always	Installed with bundled plugins	Architecture
Browser annotations	Always	Built into the patched webview	Architecture
Tray and warm-start handoff	Always	Normal app launch	Architecture
Multiple app instances	Opt-in	`./codex-app/start.sh --new-instance`	Build and packaging
Linux Computer Use backend	Bundled	MCP backend registers by default	Linux Computer Use
Linux Computer Use UI	Opt-in	`CODEX_LINUX_ENABLE_COMPUTER_USE_UI=1` or settings flag	Linux Computer Use
Linux Features framework	Opt-in	Edit `linux-features/features.json`	Linux Features
Agent Workspaces	Opt-in	`agent-workspace`	Docs
Linux AppShots	Opt-in	`appshots`	Docs
Wrapper updater button	Opt-in	`codex-wrapper-updater`	Docs
Conversation mode	Opt-in	`conversation-mode`	Docs
Copilot reasoning effort defaults	Opt-in	`copilot-reasoning-effort`	Docs
Example Linux Feature	Developer example	`example-feature`	Docs
Open Target Discovery	Opt-in	`open-target-discovery`	Docs
Read Aloud button	Opt-in	`read-aloud`	Docs
Read Aloud MCP	Opt-in	`read-aloud-mcp`	Docs
Remote Control UI gates	Opt-in	`remote-control-ui`	Docs
Experimental Remote Mobile Control	Opt-in	`remote-mobile-control`	Docs
Thorium Chrome Plugin Support	Opt-in	`thorium-chrome-plugin`	Docs
Zed Opener	Opt-in	`zed-opener`	Docs

Server-gated upstream features, such as model rollouts, are controlled by OpenAI per account. Rebuilding this wrapper does not unlock them.

Optional Linux Features

Optional Linux-only integrations live in linux-features/ and are disabled by default. They can add ASAR patches, staged resources, runtime hooks, package hooks, or legacy build/install hooks without changing the core build flow.

Enable tracked or local features before building:

cp linux-features/features.example.json linux-features/features.json

{
  "enabled": [
    "read-aloud",
    "zed-opener"
  ]
}

Private user-local features can live under the git-ignored linux-features/local/<feature-id>/ directory and use the same feature.json contract. Rebuild after changing feature choices:

make install-native

Full contract: linux-features/README.md and docs/linux-features-architecture.md.

Updates

Default native packages install codex-update-manager, a systemd --user service that checks for newer upstream DMGs, rebuilds a local native package, and installs it after Codex Desktop exits. The final install uses pkexec. Minimal window-manager sessions need a graphical polkit authentication agent for the in-app install button; otherwise the updater keeps the package ready and reports a terminal sudo /usr/bin/codex-update-manager ... --path ... command.

Manual-update package:

PACKAGE_WITH_UPDATER=0 make package
make install

Manual rebuild from a trusted checkout:

PACKAGE_WITH_UPDATER=0 make update-native

AppImage builds and repo-only generated apps do not include the native-package updater. See Updater.

Build, Package, And Run

Generate the local Electron app:

make build-app-fresh
make run-app

Use a local DMG:

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

Build and install a package:

make package
make install

Build a specific artifact:

make deb
make rpm
make pacman
make appimage

The package scripts only repackage the already-generated codex-app/. They do not download or extract the DMG themselves. See Build and packaging.

Troubleshooting

Problem	First thing to try
`/tmp` is mounted `noexec`	Set `TMPDIR` and `XDG_CACHE_HOME` to executable directories under `$HOME`
Blank window or splash stuck	Check `~/.cache/codex-desktop/launcher.log` and whether port `5175` is already in use
`CODEX_CLI_PATH` or CLI install error	Reopen the app or install `@openai/codex` manually
Wayland / GPU / Vulkan hang	Try `CODEX_LINUX_RENDERING_MODE=wayland-gpu ./codex-app/start.sh` or persistent launch flags
Resize ghosting or stale frame trails	Try `CODEX_ELECTRON_DISABLE_GPU_COMPOSITING=1 ./codex-app/start.sh` or `--disable-gpu-compositing`
Computer Use UI is hidden	Enable the UI opt-in; account/server rollouts may still hide upstream-gated parts
Computer Use has no input backend	Check `/dev/uinput`, portal support, or `ydotoold` / `ydotool.service`
Updater seems stuck	Check `codex-update-manager status --json` and service logs

Full list: Troubleshooting.