Linux native support: audit results, parity fixes, and a GPU probe

[EuVinicios]

Linux native support: audit results, parity fixes, and a GPU probe

Hi all! I've been running DSH on Linux natively (AppImage build, Ubuntu 24.04, GNOME/Wayland, NVIDIA GT 1030). I've spent a lot of time on Linux compatibility and want to share what I found, along with the fixes I've been working on. I'm sharing this in the hope it's useful as a starting point for Linux support.

Everything below is validated on a live install (0.2.2-rc.1, packaged AppImage). The clean branch with only the Linux-support commits is here: EuVinicios/deepseek-harness@linux-support (based on dsh-v0.2.2-rc.1, cherry-picked — no unrelated changes).

Download — ready to install on any Linux desktop

DeepSeek Harness for Linux — v0.2.2-rc.1 — portable AppImage (download, chmod +x, run) or the proper install via install-user.sh (menu entry, GPU acceleration enabled, dsh CLI in ~/.local/bin, atomic current symlink). SHA256SUMS included.

Note: this repo has pull requests disabled (contributions go through Discussions), so the Linux support lives on the fork's linux-support branch with a prebuilt release for anyone to install — and it's ready for upstream whenever the maintainers want it.

What I found

1. GPU acceleration works, but the launcher disables it

The packaged app is launched with --disable-gpu (software rendering). A controlled Electron probe on this machine (NVIDIA GT 1030, driver 580, Wayland/XWayland) shows that with --disable-gpu-sandbox --no-sandbox, GPU acceleration works:

• gpu_compositing: enabled
• webgl: enabled
• webgpu: enabled
• Hardware video decode: enabled
• No GPU process errors

So the real problem on this machine was not the GPU stack — it was the GPU process sandbox under XWayland. --disable-gpu-sandbox keeps the rest of the GPU pipeline intact.

2. Three parity gaps in rc.1 (Linux)

• Tray: on Linux the close button hides the window (like Windows), but there is no tray icon — so the app becomes "invisible" until relaunched. On Windows the tray is the path back; on Linux it's missing.
• Install dsh command: the menu item only exists on macOS and Windows, and the launcher script it installs (apps/desktop/cli/dsh) is hardcoded to ../MacOS/DeepSeek Harness and app.asar/dsh/... — on Linux the executable is resources/app/deepseek-harness (no FUSE). So the command would be broken even if enabled. The fix adds a Linux branch to the command-manager worker that installs into ~/.local/bin (user-writable, no elevation needed — unlike macOS's /usr/local/bin + osascript), plus the login-shell PATH lookup for shadowed-command detection (same mechanism as macOS).
• Window icon: the AppImage ships no icon entry; the desktop entry had to use icon-windows.png.

3. CLI launcher: multi-platform paths

The launcher script (apps/desktop/cli/dsh) is copied verbatim to all platforms, so it resolves the binary and the dsh tree entry per platform at runtime (uname -s):

platform	executable	dsh tree
macOS	Contents/MacOS/DeepSeek Harness	app.asar/dsh/...
Linux	deepseek-harness (beside resources/)	resources/app/dsh/... (unpacked — the bundled Node cannot read ASAR)

The cli-launcher fixture now exercises the Linux layout (binary + resources/), and the command-manager flow fixture exercises the Linux shell PATH lookup (same mechanism as macOS: detects a shadowed dsh on PATH).

4. Linux updater integration

The app's "Check for updates" button now works on Linux: the update coordinator spawns a systemd user unit (dsh-updater.service), which builds the new version from the repo and installs it atomically (symlink flip of current).

Live validation (after restart on the new build)

• Main process: --ozone-platform=x11 --disable-gpu-sandbox --no-sandbox
• GPU process: --type=gpu-process --disable-gpu-sandbox — no --use-gl=disabled (previously the GPU process was dead on arrival with --use-gl=disabled)
• Renderer: no --disable-gpu-compositing — GPU compositing is active
• Tray: created without the "desktop tray: unavailable" warning — the tray is the way back to a hidden window on Linux, same as Windows
• CLI: dsh --version → 0.2.2-rc.1 from the packaged launcher (resolves the Linux layout: binary beside resources/, dsh tree unpacked)
• Stable under load, no crashes

What I changed

• feat(linux): tray on Linux (the path back), Install dsh command enabled, window icon.
• fix(linux): build under demand via unit manual; no handoff of the same version.
• feat(linux): desktop updater integration with the native update system.
• fix(linux): desktop update channel comparison.
• build(desktop): Linux packaging scripts (package:desktop:linux-x64).
• feat(linux): Linux support for desktop packaging and runtime (initial).

Looking for feedback

• Are there other Linux parity gaps I should look at?
• Any interest in the Linux packaging scripts (package:desktop:linux-x64), or the launcher?
• What about a linux/ starter (launcher + updater unit + install.sh)? I'm happy to share it.

Thanks for the great work — the harness is the best agent harness I've used.

[X2M7]

Thanks for sharing the Ubuntu/GNOME/Wayland/NVIDIA results — the GPU-process details are especially useful. I maintain an unofficial Linux desktop port aligned with upstream 0.2.2-rc.2: source · x64/arm64 releases. It packages AppImage, deb and rpm. Both architectures passed CI packaging and packaged-runtime checks; I verified the x64 welcome window on Manjaro KDE/X11, but have not tested NVIDIA/Wayland or the arm64 GUI interactively.

Your tray finding matches a failure mode we wanted to avoid: hiding a window when no visible tray is available. Our build hides on close only when it detects a supported Linux tray host; otherwise closing quits. It also ships a bundled dsh CLI at resources/runtime/cli/bin/dsh. Updates are manual for now, so your systemd updater takes a different approach.

One question about the GPU probe: it changes both --disable-gpu-sandbox and --no-sandbox. Could you try the GPU flag without --no-sandbox to isolate the cause? Electron's sandbox documentation says --no-sandbox disables sandboxing for all processes and should only be used for testing.

I'd be glad to compare your GNOME/Wayland results with the rc.2 build and share any reproducible differences. More details about our port are in Discussion #13027.

[EuVinicios]

Great catch — and a fair methodological point: the original probe bundled both flags, so it couldn't attribute the effect. I've rerun the isolation on the same harness (Electron 44.7.0, NVIDIA GT 1030 / driver 580, GNOME-Wayland session, app under XWayland via --ozone-platform=x11), one flag at a time:

flags	result
--disable-gpu-sandbox only	FATAL at launch, before any GPU data: The SUID sandbox helper binary was found, but is not configured correctly ... chrome-sandbox is owned by root and has mode 4755 (process aborts, core dumped)
--no-sandbox only	Full hardware GPU — gpu_compositing: enabled, webgl: enabled, webgpu: enabled, video_decode: enabled, identical to the bundled run
both (original probe)	full hardware GPU

So you called it: on this distro config --disable-gpu-sandbox is redundant while --no-sandbox is present — --no-sandbox already turns sandboxing off for every process type, including the GPU process.

The flags still solve different problems, which is why the launcher keeps both:

• --no-sandbox is not a GPU workaround here — it's the only way the process starts on Ubuntu 24.04: kernel.apparmor_restrict_unprivileged_userns=1 blocks the namespace sandbox for unconfined binaries, and the unpacked/AppImage tree ships chrome-sandbox without the root-owned 4755 mode the SUID helper requires. Without it we get exactly the FATAL above, before Electron even reaches the GPU.
• --disable-gpu-sandbox stays for the config where the browser sandbox comes back on (SUID helper configured, or userns permitted): there the GPU-process sandbox under XWayland is the failure mode the flag targets. I can't run that cell of the matrix without root changes on this box — and your deb/rpm packaging presumably configures chrome-sandbox root:4755 in post-install, so if you ever probe GPU with the browser sandbox on under XWayland/NVIDIA, that fills the missing cell and I'll update the table.

The Electron-docs point is taken as well: --no-sandbox is a testing-only escape hatch. The two proper paths that let a user drop it are now in the repo (linux/hardening/): (a) the SUID helper fix above, and (b) an AppArmor profile granting userns to the binary (same pattern Ubuntu ships for chrome/chromium). After either, the browser sandbox stays on and --disable-gpu-sandbox becomes the only GPU-side switch left.

On the tray: your detect-before-hide design is better than our unconditional tray for hosts without a visible tray — hiding a window with no way back is the failure mode we hit, and your build avoids it outright. I'll look at adopting that. And the offer to compare your rc.2 build against these GNOME/Wayland/NVIDIA results cuts both ways — the probe harness is a temporary package.json swap plus one flag set, trivial to point at any unpacked build if you want the numbers on your side too.

[X2M7]

@EuVinicios Thanks for rerunning the flags one at a time. That isolates the startup blocker on your host: with the current sandbox setup, --no-sandbox gets the app running, so the original probe does not yet establish whether --disable-gpu-sandbox is needed once Chromium's sandbox works.

A detail about our rc.2 packages: the deb/rpm builds use electron-builder's conditional post-install hook. It sets chrome-sandbox to mode 4755 only when its user-namespace probe fails, and installs the bundled AppArmor profile where supported. The AppImage has no install hook, and our launcher does not add --no-sandbox. Those packaging details don't establish how the build behaves on your Ubuntu/NVIDIA host; I haven't tested that combination.

If you do try the rc.2 build there, startup and GPU-process results with the browser sandbox enabled would fill the missing comparison cell. I also couldn't access the linked dsh-linux-home-lab repo (GitHub returned 404 from my account); if you intended it to be public, could you share an accessible hardening link? Thanks for looking at the tray detection too.