English | 简体中文

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, command, and installation identity remain codex-desktop and /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. With no ASAR-changing feature enabled, resources/app.asar remains byte-for-byte identical to the official package.

Install · Uninstall · Features · Updates · Build · Troubleshooting · Docs · Discord

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

Clone the repository before building a native package or AppImage:

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

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

To choose optional features before installing:

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.

Normally the build resolves amd64 or arm64 from the signed stable index. You can instead provide a local package that you already trust:

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

The local package is still checked for package name, architecture, control metadata, payload completeness, and SHA-256 recording. Because signed repository discovery is skipped, the caller is responsible for its origin. Old .dmg, DMG=, and CODEX_DMG_* inputs are intentionally unsupported.

• 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, but both intentionally use the upstream Codex user profile. Do not run them at the same time; the upstream single-instance lock may route the second launch into the process that is already running.
• AppImage never adds --no-sandbox automatically. If your distribution disables unprivileged user namespaces, use the native package or follow the sandbox guidance in Troubleshooting.

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

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

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 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 shared Codex profile, configuration, plugins, and project state used by both official and Community applications.

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

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

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.

Native 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, and waits for the application to exit before promotion. 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 and repository-only generated apps do not include the native package updater. Full behavior and recovery steps are documented in Updater.

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

Full guide: Troubleshooting.

• 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, Validation playbook, Generated/runtime notes
• Project operations: GitHub CLI auth, Label governance

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.

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.

MIT