https://github.com/cuongducle/codex-linux
Run Codex Desktop on Linux with a lightweight wrapper, Electron rebuild flow, and local setup script.
https://github.com/cuongducle/codex-linux
app-wrapper codex codex-desktop developer-tools electron linux linux-desktop shell
Last synced: 7 days ago
JSON representation
Run Codex Desktop on Linux with a lightweight wrapper, Electron rebuild flow, and local setup script.
- Host: GitHub
- URL: https://github.com/cuongducle/codex-linux
- Owner: cuongducle
- Created: 2026-02-26T14:47:36.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-27T07:05:36.000Z (7 days ago)
- Last Synced: 2026-05-27T07:10:24.670Z (7 days ago)
- Topics: app-wrapper, codex, codex-desktop, developer-tools, electron, linux, linux-desktop, shell
- Language: Shell
- Size: 165 MB
- Stars: 16
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Codex Desktop for Linux
Unofficial Linux packaging for Codex Desktop.
## User Installation (Release Only)
End users only need files from **GitHub Releases**.
No need to clone this repo or install Node.js.
Release page: https://github.com/cuongducle/codex-linux/releases/latest
## Ubuntu Support
- Supported target: Ubuntu 22.04 and newer
- Recommended: Ubuntu 24.04 or newer
- Unsupported: Ubuntu 20.04 and older
### Option 1: Debian / Ubuntu (`.deb`)
1. Go to [Releases](https://github.com/cuongducle/codex-linux/releases/latest).
2. Download the latest `codex-desktop-*.deb` file.
3. Install:
```bash
sudo dpkg -i ./codex-desktop-*.deb
```
### Option 2: Any Distro (`.AppImage`)
1. Go to [Releases](https://github.com/cuongducle/codex-linux/releases/latest).
2. Download the latest `codex-desktop-*-x86_64.AppImage`.
3. Run:
```bash
chmod +x codex-desktop-*-x86_64.AppImage
./codex-desktop-*-x86_64.AppImage
```
### Updating
- `.deb`: download and install the newer release file.
- `.AppImage`: replace the old AppImage with the new release file.
## Maintainer Flow (Build + Publish)
### 1) Build locally
```bash
# Download upstream DMG
curl -fL "https://persistent.oaistatic.com/codex-app-prod/Codex.dmg" -o Codex.dmg
# Extract payload + rebuild Linux native modules
bash scripts/setup.sh ./Codex.dmg
# Build packages
npm run build:linux
# or separately:
# npm run build:deb
# npm run build:appimage
```
Output artifacts are in `dist/`.
### 1.1) Verify a fresh install
After installing a newly built `.deb` or launching an AppImage on a clean machine, run:
```bash
bash scripts/smoke-verify.sh
```
The smoke script verifies that `codex-desktop` resolves to the expected launcher, prints the desktop entry `Exec` lines, checks the Codex CLI path, starts the app with Electron logging enabled, and fails if bootstrap errors such as `app server has not been initialized` appear.
For packaged installs, the app executable is a wrapper that resolves `CODEX_CLI_PATH`, disables Vulkan by default, prefers X11 by default, and then launches the real Electron binary (`codex-desktop.bin`). Override graphics defaults only when needed:
```bash
CODEX_USE_X11=0 codex-desktop
CODEX_DISABLE_VULKAN=0 codex-desktop
CODEX_GL_BACKEND=desktop codex-desktop
```
### 2) Publish release
Push a version tag:
```bash
git tag v0.1.0
git push origin v0.1.0
```
GitHub Actions will automatically:
- Build `.deb` and `.AppImage`
- Upload both files to GitHub Releases
- Generate APT repository metadata (`Packages`, `Release`)
- Publish APT repo to `gh-pages`
## Daily Auto-Update
Workflow [`check-upstream.yml`](.github/workflows/check-upstream.yml) runs daily and:
- Sends a `HEAD` request to upstream `Codex.dmg` and checks `ETag` first
- If `ETag` is unchanged: skip download
- If `ETag` changed: download `Codex.dmg`, extract Codex app version from `app.asar/package.json`
- Compares that version with latest git tag (`v*`)
- If newer: updates `upstream-version.txt`, updates `upstream-etag.txt`, commits, and creates a new tag `v`
That new tag triggers the release workflow, which publishes new `.deb`, `.AppImage`, and refreshed APT metadata.
## Required Repository Settings
1. Enable GitHub Pages:
- Settings -> Pages -> Source: `Deploy from a branch`
- Branch: `gh-pages` (root)
2. Keep repository public (for public downloads).
3. Add repository secret `RELEASE_PAT` (recommended):
- Create a Personal Access Token with `repo` + `workflow` scopes.
- Save it in repo Settings -> Secrets and variables -> Actions -> `RELEASE_PAT`.
- This is used by daily update workflow to push tags that can trigger downstream release workflow.
## Features
- Packaging targets: **DEB** and **AppImage** only
- Linux native module rebuild (`better-sqlite3`, `node-pty`)
- Release CI runs on current Ubuntu runners with `dmg2img` and `7zip`
- Auto-upload release artifacts (`.deb`, `.AppImage`) to GitHub Releases
- Optional APT repo publish on release tag
## Repository Structure
- `scripts/setup.sh` - Extract from DMG, rebuild native modules, local launcher setup
- `scripts/build-packages.sh` - Build DEB/AppImage via electron-builder
- `scripts/build-apt-repo.sh` - Generate Debian repository metadata
- `scripts/generate-apt-install-script.sh` - Generate public `install.sh`
- `.github/workflows/release.yml` - CI build + release + APT publish
- `electron-builder.yml` - Packaging config
## Notes
- This is an unofficial packaging project.
- This repository does not redistribute Codex source; it builds from upstream `Codex.dmg`.
- APT setup currently uses `trusted=yes` (unsigned repository).