codex-desktop-linux

codex-desktop is an unofficial, community-maintained distribution of OpenAI's official Linux ChatGPT desktop application. It verifies and repackages the signed upstream Linux payload, adds disabled-by-default Linux features, and produces deb, RPM, pacman, AppImage, and Nix outputs.

The custom application appears in desktop menus as ChatGPT Community and uses an icon marked with a blue C. Its package and command are codex-desktop, and its installation root is /opt/codex-desktop, so it is easy to distinguish from OpenAI's separate ChatGPT package.

OpenAI's signed Linux .deb is the only upstream source. The official Electron runtime, native modules, bundled codex and rg, code-mode host, plugins, libraries, locales, and Owl metadata are reused directly. A clean build applies only required compatibility patches to resources/app.asar and preserves the official ELF runtime and bundled tools byte-for-byte. Optional Linux features remain disabled unless explicitly selected.

Before contributing, read CONTRIBUTING.md. Maintainers and coding agents should also read AGENTS.md.

Install

Clone the repository before building a native package or AppImage:

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

Platform	Recommended command	Result
Debian, Ubuntu, Pop!_OS, Mint, Elementary	make bootstrap-native	Builds and installs a .deb
Raspberry Pi 5, 64-bit OS	make bootstrap-native	Builds the official arm64 payload; see Pi notes
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
Gentoo	make bootstrap-native	Builds a local ebuild and installs through Portage; supports ui-tweaks and remote-mobile-control, no updater
NixOS or another Nix system	nix run github:ilysenko/codex-desktop-linux	Builds and runs the flake output; see Nix
Atomic desktops or another distribution	make build-app && make appimage	Produces a local AppImage without the native updater

Gentoo's application merge ignores EMERGE_DEFAULT_OPTS to install through the generated ebuild rather than reuse a binary package. Global Portage settings are unchanged. Gentoo has a phase-aware dependency and package-resource framework for audited features. ui-tweaks and remote-mobile-control are supported and remain disabled by default; other repository features require their own support declarations. Remote mobile control uses the existing Desktop-owned app-server; the ebuild does not install or enable a remote-control service. See the Gentoo feature contract. Gentoo's local ebuild path has been tested on OpenRC; a Gentoo systemd environment has not been tested. See Gentoo validation scope.

The recommended native installation is:

make bootstrap-native

This installs build dependencies, resolves the current package through OpenAI's signed stable APT metadata, builds codex-app/, creates the native package for the detected distribution, and installs the newest artifact from dist/.

If the dependencies are already installed, use:

make install-native

For the graphical guided installer, run the standalone repository entrypoint:

./install-community

(make guided-install invokes the same entrypoint.) The installer is part of the repository setup experience, not an optional Linux feature. On desktops with GTK4/PyGObject it walks through feature selection, installation options, review, and build/install progress with a live log. Required features are selected automatically; conflicting choices are disabled with the reason kept visible.

The graphical installer does not modify feature implementations or feature settings. It updates only the enabled-feature list and its own installer preferences in the gitignored linux-features/features.json; any existing feature settings are preserved unchanged. Native output always keeps the repository identity codex-desktop under /opt/codex-desktop, whether or not the automatic updater is included.

To configure features without installing yet, keep using:

make setup-native
make install-native

make setup-native only writes the local feature selection. It does not build or install the application. See Native setup for the guided flow, non-interactive settings, updater selection, and cleanup.

Use an already downloaded official package

Normally the build resolves amd64 or arm64 from the signed stable index. You can reuse an already-downloaded package body:

UPSTREAM_DEB=/path/to/chatgpt_<version>_<arch>.deb make build-app

The local package is verified against the signed stable metadata by default, including its version, architecture, size, and SHA-256, without downloading its body again. All builds verify without prompting or reading user input, including interactive local builds. To choose the local exception explicitly:

./install.sh --skip-oai-official-sig-verification /path/to/chatgpt_<version>_<arch>.deb

The exception applies only to this invocation and still checks package name, version format, architecture, and payload completeness. Build metadata records signatureVerification: "skipped"; the caller is responsible for provenance. Verification errors never silently enable the exception. See Build and packaging. Old .dmg, DMG=, and CODEX_DMG_* inputs are intentionally unsupported.

Before you install

• Only the latest signed stable OpenAI Linux package is supported, on amd64 and arm64.
• Build tools require Node.js 20 or newer, npm, Python 3, curl, gpgv, dpkg-deb, tar, make, and a C/C++ toolchain. Rust is used for the updater and enabled native feature helpers. make bootstrap-native installs or guides you through these requirements.
• The official chatgpt and custom codex-desktop packages may coexist. By default they intentionally share the upstream Codex user profile and should not run at the same time. The optional community-profile-isolation feature gives Community separate Codex and Electron state and pins its bundled CLI so users who need isolated runtimes can avoid that shared-profile boundary.
• AppImage never adds --no-sandbox automatically. If your distribution disables unprivileged user namespaces, use the native package or follow the sandbox guidance in Troubleshooting.

Anonymous daily usage count

To help the community decide whether maintaining this distribution is useful, the launcher sends at most one anonymous usage event per UTC day to the public GoatCounter dashboard. The event contains only the fixed path /app-launch. GoatCounter derives an aggregate country from the network request; no application activity, account or machine identifier, version, architecture, package format, language, screen size, or referrer is sent. Every installation sends the same fixed, non-identifying User-Agent so GoatCounter does not discard the request as a bot.

The request runs silently in the background. A missing curl, a blocked request, or any other error never delays the application and produces no output. Disable the usage count with the single environment variable:

CODEX_LINUX_DISABLE_USAGE_REPORTING=1 codex-desktop

Uninstall

First close both ChatGPT Community and the official ChatGPT application. Then remove the native package with the package manager that installed it:

# 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

# Gentoo
sudo emerge --deselect app-misc/codex-desktop
sudo emerge --unmerge app-misc/codex-desktop

Native package removal disables the user update service. If a service from an older or manual installation remains, remove it explicitly:

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

For AppImage, delete the AppImage file you built. For a repository-only app, delete only the generated tree inside the checkout:

rm -rf -- ./codex-app

For Nix, remove the package from your profile, Home Manager configuration, or NixOS module and rebuild that profile or system.

Package removal preserves user data. To remove only Community wrapper and updater state, inspect and then delete the following directories:

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

If community-profile-isolation was enabled, its Community-owned state is ~/.codex-community and its Electron profile is ~/.config/Codex-Community. Remove those paths only when you intentionally want to delete that isolated Community data.

If remote-mobile-control was enabled, revoke paired devices before removing its private device keys. Do not remove ~/.codex unless you intentionally want to delete the default shared Codex profile, configuration, plugins, and project state.

Feature matrix

Core distribution

Capability	Default	How it is provided
Official ChatGPT Linux runtime	Always	Copied from the verified official .deb data payload
Signed source verification	Enabled	Pinned repository key → InRelease → Packages SHA-256 → package SHA-256; explicit local exceptions are recorded
Native deb, RPM, and pacman packages	Manual build	make deb, make rpm, or make pacman
AppImage	Manual build	make appimage; no automatic sandbox bypass or bundled updater
Nix flake	Manual build	nix run github:ilysenko/codex-desktop-linux
Transactional update manager	Native packages	Included unless built with PACKAGE_WITH_UPDATER=0
Official Browser and Chrome integrations	Upstream	Reused from the official Linux package; no legacy port layer
Focusable Quit confirmation	Always	Required compatibility patch parents the upstream confirmation on Linux
Optional Linux feature framework	Disabled	Configure with make setup-native
Distinct desktop identity	Always	ChatGPT Community, blue C icon, codex-desktop package identity

Optional Linux features

Every feature below is disabled by default. Its adjacent README describes requirements, known limitations, configuration, and tests.

Feature ID	Purpose	Documentation
account-switcher	Experimental encrypted ChatGPT login switching from the profile menu; requires Secret Service and secret-tool; shares local chats and settings	Docs
agent-workspace	Agent-workspace settings and bridge for hidden desktop environments	Docs
api-key-model-visibility	Show models reported by API-key authenticated compatible providers	Docs
api-key-service-tier	Fast/service-tier UI for API-key authenticated compatible providers	Docs
appshots	Capture and crop the focused Linux window from the composer	Docs
authored-message-visibility	Keep assistant and user messages visible after tool activity collapses	Docs
authenticated-proxy	Username/password support for HTTP proxies	Docs
automation-extensions	Multi-time schedules and eager automation_update exposure

For GNOME Wayland dictation without RemoteDesktop permission prompts, select both global-dictation and global-dictation-gnome with make setup-native, then rebuild/install. The first app launch installs the companion for the current user; log out/in and explicitly enable it with gnome-extensions enable [email protected]. Restart the app/helper after enabling the extension. The helper automatically checks the companion's version at startup: a compatible enabled extension selects GNOME; otherwise it selects RemoteDesktop. This choice stays fixed until restart. Once GNOME is selected, paste errors never fall back to RemoteDesktop or retry. The build feature only ships/installs the companion; a manually installed compatible extension is also detected. Shortcut approval still uses GlobalShortcuts. Disabling the build feature does not uninstall the user extension; see its activation and removal instructions.

The optional Computer Use backend provides guard-accessibility for an explicit foreground GNOME accessibility hold-open. It never starts automatically; see Linux Computer Use.

With shared-app-server-socket enabled and Desktop running, use codex-desktop --cli to attach Codex CLI to Desktop's app-server. See Attached CLI.

Account rollouts and server-side ChatGPT features remain controlled by OpenAI. Rebuilding this project does not unlock an account rollout.

For CSS font fallback lists, the optional ui-tweaks custom font input adds a switch between installed-font lists and manual font-stack entry in Appearance. This nested tweak is disabled by default and must be enabled in local feature settings before rebuilding.

The optional ui-tweaks sub-option tweaks.selection.moreDetails.enabled restores More details in the Codex reply selection menu, asking ChatGPT Quick Chat to explain the selected text with its source context. It is disabled by default; see the UI Tweaks configuration.

When testing a local build, launch codex-app/start.sh with the same Electron flags as your normal desktop entry, including any required --proxy-server=... argument. Quick Chat becomes available after ChatGPT account initialization.

The optional ui-tweaks sub-option tweaks.selection.annotationSubmit.enabled makes Ctrl+Enter send the active selected-text annotation editor's text without being intercepted by the regular composer; it is disabled by default. See the annotation submit configuration.

Configure optional features

The recommended editor is the setup wizard:

make setup-native

For manual configuration, copy the example to the gitignored local file:

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

{
  "enabled": [
    "read-aloud",
    "ui-tweaks"
  ]
}

Then rebuild and install:

make install-native

Private features may live under the gitignored linux-features/local/<feature-id>/ tree and use the same manifest contract. Known retired IDs are ignored to migrate old local configs; arbitrary unknown IDs and misspellings remain errors. See the feature framework README and feature architecture.

Updates

deb, RPM, and pacman packages include codex-update-manager by default. Its user service polls the same signed APT metadata, caches official packages by version/architecture/SHA-256, reconstructs the selected native package with the currently enabled features in a separate workspace, and waits for the managed application to exit before an authorized package-manager install. A durable transaction supports recovery from interrupted or partially applied installs; this does not use the manual generated-tree directory exchange. The immediately previous managed package remains available for rollback.

codex-update-manager status
codex-update-manager status --json
codex-update-manager check-now
codex-update-manager diagnose
codex-update-manager install-ready
codex-update-manager rollback

systemctl --user enable --now codex-update-manager.service
systemctl --user status codex-update-manager.service
journalctl --user -u codex-update-manager.service

Build a manual-update package without the service:

PACKAGE_WITH_UPDATER=0 make package
make install

AppImage, repository-only generated apps, Nix, and manual-update Gentoo outputs do not use the native package updater. Full behavior and recovery steps are documented in Updater.

Build, package, and run

# Build the local application tree and run it without installing a package
make build-app
make run-app

# Build and install the package format detected for this distribution
make package
make install

# Build a specific output
make deb
make rpm
make pacman
make appimage

Builds are transactional: a candidate is verified before it replaces the working tree. Enabled ASAR-feature drift rejects a candidate; disabled features are not probed. Package scripts consume the generated codex-app/ tree. See Build and packaging for prerequisites, variables, output layout, parallelism, and payload inspection.

Troubleshooting

Problem	First check
Official and Community launches interfere	Fully exit every ChatGPT process; both apps share the upstream profile
AppImage opens from Flatpak Chrome, but the extension says Native transport disconnected	Enable flatpak-chrome-native-messaging; see Flatpak Chrome setup
Browser/Chrome extension cannot connect after migration	Exit ChatGPT and Chrome completely, then follow the narrow cache repair in Troubleshooting
Signature or package verification fails	Check time, network, gpgv, architecture, and disk space; intentional unverified local builds require the documented explicit flag
App does not launch	Run /opt/codex-desktop/start.sh --diagnose
App uses XWayland or needs persistent Electron flags	A confirmed Wayland session selects the native backend automatically; pin one with CODEX_OZONE_PLATFORM=x11|wayland, or put one flag per line in ~/.config/codex-desktop/electron-flags.conf, for example --ozone-platform=x11
AppImage reports a sandbox error	Enable user namespaces or install a native package; --no-sandbox is not added automatically
Enabled feature drifts after an upstream release	Disable that feature to confirm the clean baseline and attach its patch report to an issue
Updater waits for application exit	Close the managed app (default /opt/codex-desktop/ChatGPT); inspect appExecutable and appRunning with codex-update-manager diagnose --json
Old codex-app.backup-* reports permission errors	Inspect the exact path and follow the root-owned backup procedure; never delete a wildcard blindly

Full guide: Troubleshooting.

Project documentation

• Getting started: Native setup, Build and packaging, Nix, Raspberry Pi 5
• Runtime and maintenance: Architecture, Updater, Troubleshooting
• Extensions: Feature framework, Feature architecture, Linux Computer Use, Record and Replay, Chronicle / Skysight
• Contributors: Contributing, Agent instructions, Repository map, ,

Historical macOS DMG conversion, downloaded Electron replacement, native-module rebuild, local webview server, and custom warm-start documents are intentionally not active documentation: the official Linux package now owns those runtime responsibilities.

Disclaimer

This is an unofficial community project and is not affiliated with OpenAI. ChatGPT, OpenAI services, trademarks, upstream application code, binaries, and assets remain the property of OpenAI or their respective owners.

The repository downloads and repackages the official Linux payload locally; it does not grant rights to OpenAI software or services. Use of ChatGPT remains subject to OpenAI's applicable terms and server-side feature availability.

The MIT license applies only to this repository's wrapper source, packaging, documentation, and community-owned extensions.

License

MIT