Run ZCode v3.0.0 on Ubuntu/Debian x64, even though Z.AI officially publishes v3 for macOS and Windows only. This repo ships the automation that performs the port — it downloads everything from ZCode's official CDN at install time and redistributes no proprietary binaries.
-9cf){kind=icon}
git clone https://github.com/roman-ryzenadvanced/ZCode-v3-Linux-Port.git
cd ZCode-v3-Linux-Port
chmod +x install.sh revert.sh verify.sh
sudo ./install.sh # downloads official builds + performs the port
./verify.sh # confirm v3 is active
/opt/ZCode/zcode & # launchTo undo:
sudo ./revert.shZCode is Z.AI's AI coding desktop app (deeply integrated with GLM models). Its v3.0.0 release (2026-06-13) brought a self-built agent core, GLM-5.2 tuning, grouped task workspaces, Git branch graphs, and more — but it shipped only for macOS (Apple Silicon) and Windows.
| Platform | v2.13.0 (last with Linux) | v3.0.0 |
|---|---|---|
| macOS (arm64) | ✅ | ✅ |
| Windows (x64) | ✅ | ✅ |
| Linux (x64) | ✅ | ❌ dropped |
The Linux electron-builder update feed still serves 2.13.0, so the in-app updater on Linux will never offer 3.0:
https://cdn.zcode-ai.com/zcode/electron/releases/update/linux/x64/latest-linux.yml
→ version: 2.13.0
This repo is a community workaround for Linux users who want v3.
ZCode is an Electron app. An Electron app is split into two layers:
- The shell — the Electron runtime + Chromium binaries (
/opt/ZCode/zcode,libffmpeg.so, GPU libs, etc.). These are platform-specific (Linux ELF, macOS Mach-O, Windows PE). - The application code — packaged in
resources/app.asar, a single archive of platform-agnostic JavaScript. Plus a few helper resources (resources/glm/,resources/model-providers/).
The native Node addons (terminal emulator node-pty, SSH client ssh2) live in
resources/app.asar.unpacked/ and ship prebuilt per-platform.
The key insight that makes this port possible:
v3.0.0 was built with the exact same Electron 41.0.3 / Chrome 146 and the exact same native dependency versions (
node-pty ^1.0.0,ssh2 ^1.16.0) as v2.13.0. The Node native-addon ABI is therefore identical across the two versions, so v2.13's Linux prebuilds load cleanly under v3's code.
That means the port is just a surgical file swap: take v3's
platform-agnostic app.asar + glm/ + model-providers/, drop them into the
existing v2.13 Linux shell, and leave the Linux-native bits alone.
| Path | Action | Why |
|---|---|---|
resources/app.asar |
Replace with v3 | The v3 application code (JS) |
resources/glm/ |
Replace with v3 | v3 ships zcode.cjs (Node script) + plugin packages; v2.13 had a native zcode-acp ELF |
resources/model-providers/ |
Add (new in v3) | v3's model catalog JSON |
resources/app.asar.unpacked/ |
KEEP v2.13 | Linux node-pty + ssh2 native prebuilds (mac ones are arm64 Mach-O) |
resources/tools/ripgrep/rg |
KEEP v2.13 | Linux static binary (mac one is arm64 Mach-O) |
resources/app-update.yml |
KEEP v2.13 | Points at the Linux update feed (v3's points at mac) |
install.sh automates all of this, with a full backup for one-command revert.
⚠️ v3 also dropped the bundledcodex/,gemini/,opencode/,acp/helper directories (the changelog says it no longer bundles other agents). Any leftover v2.13 copies are simply ignored by v3 — harmless.
- Ubuntu / Debian x86-64 (other distros with
dpkgwork; AppImage base also possible with minor edits) sudo(writes to/opt/ZCode)curl,unzip,strings,sha512sum(all standard)- Enough disk: ~300 MB for downloads + ~200 MB backup
- A working display (it's a GUI app)
sudo ./install.shWhat it does, step by step:
- Ensures the v2.13 Linux base is installed. If
/opt/ZCode/zcodedoesn't exist, it downloads the officialZCode-2.13.0-linux-x64.deband installs it withapt/dpkg. - Stops any running ZCode.
- Downloads
ZCode-3.0.0-mac-arm64.zipfrom ZCode's CDN and verifies its SHA-512 against the checksum published in the official mac update feed (latest-mac.yml). - Backs up your current
resources/to/opt/ZCode/resources.backup-2.13.<timestamp>/. - Performs the swap (replace
app.asar+glm/, addmodel-providers/, preserve the Linux-native parts). - Verifies the new version and that the Linux
node-ptyprebuild survived.
Then launch from your app menu, or:
/opt/ZCode/zcode &./verify.shChecks: app.asar is present, the Linux node-pty prebuild exists, ripgrep is
the Linux binary, the update feed still points at Linux, and the runtime log
shows version: 3.0.0.
You can also confirm directly:
grep "current version" ~/.zcode/v2/logs/$(date +%F).log | tail -1
# expect: current version: 3.0.0sudo ./revert.sh # uses the recorded backup
sudo ./revert.sh /opt/ZCode/resources.backup-2.13.20260614-130112 # explicitRestores the original v2.13 app.asar, app.asar.unpacked, glm/, tools/,
and app-update.yml, and removes the v3-only model-providers/ directory.
See docs/HOW_IT_WORKS.md for:
- The Electron version match that makes this safe
- The exact native-module ABI story (
NODE_MODULE_VERSION) - Why we use the mac-arm64 zip (not Windows) as the v3 source
- The structure of
app.asarvsapp.asar.unpacked - What happens with the (oddly aarch64)
sshcrypto.nodein the amd64 deb
See docs/TROUBLESHOOTING.md for common failures.
Bump the three variables at the top of install.sh:
readonly V3_VERSION="3.1.0"
readonly V3_MAC_ZIP_URL="https://cdn.zcode-ai.com/zcode/electron/releases/3.1.0/ZCode-3.1.0-mac-arm64.zip"
readonly V3_MAC_ZIP_SHA512="<new sha512 from latest-mac.yml>"Critical pre-flight check: verify the new build's Electron major matches
the installed Linux shell's Electron major. If they diverge, the Linux
node-pty prebuild will fail ABI (was compiled against a different Node.js version) and the terminal pane will break. In that case you must either wait
for an official Linux build or rebuild node-pty for the new ABI.
# Linux shell Electron:
strings /opt/ZCode/zcode | grep -oE "Electron/[0-9.]+" | head -1
# v3 mac Electron (from the zip you're about to use):
strings "ZCode.app/Contents/Frameworks/Electron Framework.framework/Electron Framework" \
| grep -oE "Electron/[0-9.]+" | head -1- ZCode is proprietary software owned by Z.AI (智谱). This project does
not redistribute any ZCode binaries,
app.asar, native modules, or artwork. Every binary is downloaded at install time from ZCode's own CDN. - This repo provides only automation scripts and documentation describing a personal-use file transformation on software the user has legitimately installed — for interoperability with Linux, a platform the vendor currently doesn't publish for.
- This project is not affiliated with, endorsed by, or sponsored by Z.AI.
- Use at your own risk. If an official Linux build is published, prefer it.
- The
LICENSE(MIT) covers this repository's scripts and documentation only, not ZCode itself.
- Procedure discovered and validated on Ubuntu x64, 2026-06-14.
- Thanks to Z.AI for shipping the same Electron version across platforms in v3.
MIT — see LICENSE (applies to scripts/docs in this repo only).