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; audited features only, 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, remote-mobile-control and
community-features-in-gui-settings 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. The read-only
community catalog is embedded in ASAR and needs no extra Gentoo dependency or
updater snapshot; see its Gentoo scope
and 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
This is the beginning of the README. Read the rest at the original. Read the full README ↗
