fix(desktop): enable AppImage to run on modern Linux without installing libfuse2

[yomgui]

PR: fix(desktop): enable AppImage to run on modern Linux without installing libfuse2

Summary

From a user perspective, this PR ensures that the Linux AppImage launches successfully on modern Linux installations (such as Fedora Silverblue 44) without requiring the installation of the legacy FUSE2 (libfuse.so.2) package. Startup, direct installation, and automatic update flows remain fully functional and seamless.

Technically, this is achieved by upgrading electron-builder to 26.15.3 and opting into the official static AppImage runtime toolset (toolsets.appimage: "1.0.3"). This natively compiles the AppImage without FUSE2 dynamic links inside the standard build pipeline, avoiding custom post-build repackaging scripts and preserving updater metadata, SHA-512 checksums, and blockmap integrity.

Why

Previously, the Linux AppImage produced by electron-builder on the dev branch used the legacy AppImageKit 12 runtime, which dynamically loads libfuse.so.2 (FUSE2) at launch. On modern Linux distributions (such as Fedora Silverblue 44) that only ship with FUSE3 by default, the AppImage fails immediately with:

dlopen(): error loading libfuse.so.2
AppImages require FUSE to run.

An experimental attempt to repack the AppImage with a post-build script was rejected because it bypassed the standard release pipeline and invalidated the updater manifest metadata and blockmap integrity. Opting into the native static runtime is the clean, supported way to fix FUSE3 compatibility without side effects.

---

Comparison: dev vs. fix/appimage-static-runtime

Metric / Aspect	Before (dev baseline)	After (fix/appimage-static-runtime)
Commit	e8ab197c5	ab852b090
AppImage Toolset	Default (AppImageKit 12)	Static Runtime 1.0.3
Runtime Version	effcebc (2019)	type2-runtime commit dd6cebe
FUSE Dependency	Dynamic link to libfuse.so.2 (FUSE2)	FUSE3-capable / static runtime
AppImage Size	217 MB (217,316,064 bytes)	201 MB (201,262,796 bytes)
Fedora Silverblue 44 Host	Fails to launch (Exit 1, FUSE2 load error)	Launches successfully (Electron starts, workspace server responds)
Updater Metadata	Valid	Valid (SHA-512 & blockmap size match final build natively)
Custom Scripts	None	None (Clean electron-builder.yml integration)

---

Issue

• None (Resolves FUSE2 runtime issues on modern FUSE3-only Linux environments)

Scope

• Upgraded electron-builder from 25.1.8 to 26.15.3 in package.json to gain static runtime toolset support.
• Configured toolsets.appimage: "1.0.3" in electron-builder.yml.
• Standardized the executable name to openwork (required by the modern builder's safety constraints).
• Created automated fraimz verification flow in appimage-static-runtime.flow.mjs.

Out of scope

• Custom download/repack scripts (completely avoided).
• Non-Linux targets (macOS and Windows targets are unaffected).

Testing

Ran

• pnpm install --frozen-lockfile
• pnpm --filter @openwork/desktop test
• pnpm --filter @openwork/desktop typecheck:electron
• pnpm --filter @openwork/desktop package:electron
• pnpm fraimz --flow appimage-static-runtime

Result

• Passed: All tests passed. The fraimz verification flow completed successfully (1 passed, 0 failed), validating that:
  • The baseline AppImage from dev fails to run on FUSE3-only Fedora Silverblue 44 with a FUSE2 loading error.
  • The new AppImage built from fix/appimage-static-runtime launches successfully, initializes Electron, and runs the workspace server successfully on the same FUSE3-only host.
  • The updater manifest matches the final AppImage's size and SHA-512 perfectly, preserving blockmap integrity.

CI status

• pass: Pending (PR not yet pushed/opened on GitHub)
• code-related failures: None (all checks passed locally)
• external/env/auth blockers: None

Manual verification

1. Build the desktop app:

   pnpm --filter @openwork/desktop package:electron

2. Verify the built AppImage runtime version (should show modern type2-runtime):

   ./apps/desktop/dist-electron/openwork-linux-x86_64-*.AppImage --appimage-version

3. Run the AppImage on a FUSE3-only host (e.g. Fedora Silverblue 44 without libfuse.so.2) and verify it launches and connects successfully.

Evidence

• Fraimz proof: fraimz.html
• Full writeup: appimage-static-runtime.md
• Note on video/screenshots: This is an internal (app-less) cli/build verification run. No UI/CDP interactions are involved, so no video or screenshots are captured. The raw command executions and system audits are fully asserted and witnessed within the fraimz.html report.

Risk

• Low. Uses official, built-in features of electron-builder natively, avoiding any custom or unsafe post-build repack steps.

Rollback

• Revert electron-builder to 25.1.8 in apps/desktop/package.json and remove the toolsets.appimage block in apps/desktop/electron-builder.yml.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
openwork-landing	Ready	Preview, Comment, Open in v0	Jul 11, 2026 9:36pm

[vercel]

@yomgui is attempting to deploy a commit to the Different AI Team on Vercel.

A member of the Team first needs to authorize it.