Before opening a pull request, read CONTRIBUTING.md.

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.

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, validates the cached upstream Codex.dmg, downloads it only when missing or stale, 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 make gcc-c++ @development-tools

# Fedora < 41
sudo dnf install python3 p7zip p7zip-plugins curl unzip rpm-build make gcc-c++
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.

Uninstall

Close Codex Desktop first, then remove the native package with your distro's package manager:

# Debian / Ubuntu
sudo apt remove codex-desktop

# Fedora
sudo dnf remove codex-desktop

# openSUSE
sudo zypper remove codex-desktop

# Arch / Manjaro
sudo pacman -R codex-desktop

Native package removal stops and disables codex-update-manager.service when the service is installed. If the service was left behind by an older package or a manual install, disable it explicitly:

systemctl --user disable --now codex-update-manager.service

AppImage builds are not installed system-wide by this repository; delete the AppImage file you created. A repo-only generated app can be removed from the checkout with:

rm -rf codex-app

nix run github:ilysenko/codex-desktop-linux is ephemeral. If you installed the flake through a Nix profile, Home Manager, or a NixOS module, remove that profile or configuration entry and rebuild your profile/system.

User data is preserved for reinstall. To remove only this wrapper's local app state, logs, launcher flags, and updater state, delete these paths.

If you enabled Remote Mobile Control, ~/.config/codex-desktop can contain remote-control-device-keys-v1.json. Revoke paired devices in Codex Settings/Connections or ChatGPT before deleting that file or removing the whole directory. For feature-owned data, prefer the cleanup flow in Native setup.

rm -rf \
  ~/.config/codex-desktop \
  ~/.local/state/codex-desktop \
  ~/.cache/codex-desktop \
  ~/.config/codex-update-manager \
  ~/.local/state/codex-update-manager \
  ~/.cache/codex-update-manager

Do not remove ~/.codex unless you also want to delete your Codex CLI configuration and project state.

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. The launcher does not rank installed CLIs by version; it uses an explicit CODEX_CLI_PATH first, then the normal lookup order, and logs the resolved CLI path plus best-effort version so GUI PATH issues are visible. Set CODEX_CLI_PATH=/path/to/codex when you want to pin a specific binary.

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
Record and Replay (alpha)	Opt-in alpha	record-and-replay	Docs
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
API key service tier	Opt-in	api-key-service-tier	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

Additional opt-in features, including proxy, titlebar, process cleanup, status-panel, and X11 Computer Use adapters, are documented under linux-features/.

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",
    "open-target-discovery"
  ]
}

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	Check ~/.cache/codex-desktop/launcher.log, set CODEX_CLI_PATH=/path/to/codex to pin a binary, or install @openai/codex manually
Wayland / GPU / Vulkan hang	Try CODEX_LINUX_RENDERING_MODE=wayland-gpu ./codex-app/start.sh or persistent launch flags
UI oversized or blurry (HiDPI / fractional scaling)	Try CODEX_FORCE_DEVICE_SCALE_FACTOR=1 ./codex-app/start.sh or CODEX_OZONE_PLATFORM=x11 ./codex-app/start.sh; see ./codex-app/start.sh --diagnose-scaling
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.

Project Docs

• Native setup
• Nix
• Linux Computer Use
• Record and Replay on Linux
• Updater
• Build and packaging
• Troubleshooting
• Architecture
• GitHub CLI auth in app-launched shells
• Linux Features architecture
• Wayland input focus investigation
• Webview server evaluation
• Launcher performance notes

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