The best way to control Claude Code, Codex and more from any computer or phone
fix(desktop): prepare server bytecode on Linux ARM64 (#33050)
Enable prepared server bytecode on native Linux ARM64 desktop builds and install the Electron runtime libraries required to generate it on headless Linux runners. Keep host compatibility checks and extend the existing tests. Document the native ARM64 command and supported build prerequisites. Validated with check:changed, native ARM64 tests, AppImage and .deb builds, and packaged Electron accepting the prepared CLI and server bytecode after extraction. CI and bot reviews passed on 8f893924530b4c713b39661b5e50757934f24e1d. Implemented and verified by GPT 6.1 Sol through the Codex harness.
Yash Singh committed
Nov 8, 2026 at 14:06 UTC
3da48c1234045f89bac7db885bbee73464a60624
4 files changed
+25
-15
.github/workflows/release-desktop.yml
+1
-1
@@ -478,7 +478,7 @@ jobs:
478
shell: bash
479
run: |
480
sudo apt-get update
481
- sudo apt-get install -y libsecret-1-dev pkg-config
481
+ sudo apt-get install -y libsecret-1-dev pkg-config libgtk-3-0t64 libnss3 libasound2t64 libgbm1
482
if ! command -v magick >/dev/null 2>&1 && ! command -v convert >/dev/null 2>&1; then
483
sudo apt-get install -y imagemagick
484
fi
docs/operations/development.md
+17
-6
@@ -264,13 +264,19 @@ vp run dist:desktop:linux
264
vp run dist:desktop:win
265
```
266
267
+`dist:desktop:linux` targets x64. For a native Linux ARM64 build, run:
268
+
269
+```sh
270
+vp run dist:desktop:artifact --platform linux --target AppImage --arch arm64
271
+```
272
+
273
DMGs default to the host architecture. Use `--arch` to choose another target and `--keep-stage`
274
to retain packaging files for inspection. Run `vp run dist:desktop:artifact --help` for other
275
options.
276
277
### Prepared server bytecode
278
273
-Native macOS and Windows desktop artifact builds, and native Linux x64 builds, generate server
279
+Native macOS and Windows desktop artifact builds, and native Linux x64 and ARM64 builds, generate server
280
bytecode with the packaged Electron executable, after ASAR creation and before signing. Generation imports the CLI and server
281
module declarations without launching server services; worker-only modules compile normally.
282
AppImage backends use temporary links for each mount and remove them on normal exit. Later launches
@@ -296,25 +302,30 @@ keeps the explicit flush needed when Windows force-kills the backend.
302
### Linux AppImage prerequisites
303
304
Build on Linux because the browser-secret helper links against the host's libsecret. Install
299
-Rust, C/C++ build tools, libsecret development headers, pkg-config, and ImageMagick.
305
+C/C++ build tools, libsecret development headers, pkg-config, and ImageMagick.
306
+Bytecode preparation also runs packaged Electron and requires GTK, NSS, ALSA, and GBM runtime libraries.
307
+Install Rust 1.95 or newer through [rustup](https://rust-lang.org/install), using the stable
308
+toolchain as release CI does.
309
301
-Ubuntu and Debian:
310
+Ubuntu 24.04 and Debian 13:
311
312
```sh
313
sudo apt-get update
305
-sudo apt-get install cargo rustc build-essential libsecret-1-dev pkg-config imagemagick
314
+sudo apt-get install build-essential libsecret-1-dev pkg-config imagemagick libgtk-3-0t64 libnss3 libasound2t64 libgbm1
315
```
316
317
+On Ubuntu 22.04 and Debian 12, use `libgtk-3-0` and `libasound2` instead of the `t64` packages.
318
+
319
Fedora:
320
321
```sh
311
-sudo dnf install rust cargo gcc gcc-c++ make libsecret-devel pkgconf-pkg-config ImageMagick
322
+sudo dnf install gcc gcc-c++ make libsecret-devel pkgconf-pkg-config ImageMagick gtk3 nss alsa-lib mesa-libgbm
323
```
324
325
Arch Linux:
326
327
```sh
317
-sudo pacman -S rust base-devel libsecret pkgconf imagemagick
328
+sudo pacman -S base-devel libsecret pkgconf imagemagick gtk3 nss alsa-lib mesa
329
```
330
331
The C toolchain, pkg-config, and libsecret headers are also needed for Linux desktop development.
scripts/lib/server-compile-cache.test.ts
+7
-4
@@ -8,7 +8,8 @@ import { cacheKey, seedPreparedCache } from "./server-compile-cache.ts";
8
9
it.each([
10
{ platform: "freebsd", hostArch: "x64", arch: 1, reason: "unsupported target freebsd" },
11
- { platform: "linux", hostArch: "arm64", arch: 3, reason: "unsupported Linux architecture arm64" },
11
+ { platform: "linux", hostArch: "x64", arch: 3, reason: "unexecutable target linux/arm64" },
12
+ { platform: "linux", hostArch: "arm64", arch: 1, reason: "unexecutable target linux/x64" },
13
])(
14
"skips unsupported $platform/$hostArch cache generation",
15
async ({ platform, hostArch, arch, reason }) => {
@@ -36,11 +37,13 @@ it.each([
37
{
38
platform: "darwin",
39
hostArch: "arm64",
40
+ arch: 1,
41
resources: "Fixture.app/Contents/Resources",
42
executable: "Fixture.app/Contents/MacOS/Fixture",
43
},
42
- { platform: "linux", hostArch: "x64", resources: "resources", executable: "fixture" },
43
-])("prepares $platform x64 cache", async ({ platform, hostArch, ...layout }) => {
44
+ { platform: "linux", hostArch: "x64", arch: 1, resources: "resources", executable: "fixture" },
45
+ { platform: "linux", hostArch: "arm64", arch: 3, resources: "resources", executable: "fixture" },
46
+])("prepares $platform/$hostArch cache", async ({ platform, hostArch, arch, ...layout }) => {
47
const { spawnSync } = await import("node:child_process");
48
const root = NodeFS.realpathSync(
49
NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-hook-cache-")),
@@ -76,7 +79,7 @@ it.each([
79
Object.defineProperty(process, "platform", { value: ${JSON.stringify(platform)} });
80
Object.defineProperty(process, "arch", { value: ${JSON.stringify(hostArch)} });
81
require(${JSON.stringify(hook)})({
79
- appOutDir: ${JSON.stringify(root)}, electronPlatformName: ${JSON.stringify(platform)}, arch: 1,
82
+ appOutDir: ${JSON.stringify(root)}, electronPlatformName: ${JSON.stringify(platform)}, arch: ${arch},
83
packager: { appInfo: { productFilename: "Fixture" }, executableName: "fixture" }
84
}).catch(error => { console.error(error); process.exitCode = 1; });
85
`,
scripts/prepare-server-compile-cache.cjs
-4
@@ -11,10 +11,6 @@ module.exports = async ({ appOutDir, electronPlatformName, arch, packager }) =>
11
return;
12
}
13
const targetArch = ["ia32", "x64", "armv7l", "arm64", "universal"][arch];
14
- if (electronPlatformName === "linux" && targetArch !== "x64") {
15
- console.log(`[server-compile-cache] Skipping unsupported Linux architecture ${targetArch}`);
16
- return;
17
- }
14
const runsWithRosetta =
15
electronPlatformName === "darwin" &&
16
process.platform === "darwin" &&