Codex Desktop for Linux

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
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.

Project Docs

• Native setup
• Nix
• Linux Computer Use
• Updater
• Build and packaging
• Troubleshooting
• Architecture
• GitHub CLI auth in app-launched shells
• Linux Features architecture
• Webview server evaluation

Disclaimer

This is an unofficial community project. Codex Desktop is a product of OpenAI. This tool does not redistribute any OpenAI software; it automates the conversion process that users perform on their own copies.

License

MIT