English | 中文

deepseek-harness-linux-desktop

Unofficial patch set that gives the DeepSeek Harness desktop app a Linux x64 release target (AppImage + deb) and brings its behaviour in line with the macOS build.

Upstream ships macOS and Windows only — its own apps/desktop/README.md states "Linux is not a supported Desktop release target", and the packaging tests assert that a linux-x64 target must be rejected. This repository is the set of diffs that opens that path up.

Status: Linux x64 verified on Ubuntu 24.04 LTS and Debian 13 (trixie) in GitHub Actions, and locally. The twelve-patch series applies cleanly to the upstream tag and has been compiled, packaged, and smoke-tested on Ubuntu 24.04 x86_64, and the whole chain (including installing the deb and booting the AppImage) also runs inside a Debian 13 container. The verified build produced both an AppImage and a deb; the AppImage was also started from its self-extracting mode because the authors' host does not have libfuse.so.2. patches/0009–0012 fix what the first real Linux runs surfaced: a TS2339 failure in the typecheck, a dsh launcher that could never find its payload, an upload-plan error message that dropped the environment name, and four style / repository-reference errors that upstream's own Linux gate rejects.

Base: upstream tag dsh-v0.2.0-rc.2 (commit 639ed0153972), 12 patches.

---

Table of contents

• 1. What you get
• 2. Requirements and fixed paths
• 3. Build — one-shot script
• 4. Build — step by step (with success conditions)
• 5. Acceptance checklist (the 7 behaviours)
• 6. Artifacts and where they land
• 7. Failure triage
• 8. Verified / not verified
• 9. Known limits
• 10. Layout, license, attribution

---

1. What you get

#	macOS behaviour	How the patch set delivers it on Linux
1	App starts	The desktop policy gate no longer throws desktop policy: unsupported platform on Linux
2	Window chrome	titleBarStyle: 'hidden' + titleBarOverlay (the same mechanism Windows uses), so the page owns the titlebar area; DSH_DESKTOP_LINUX_NATIVE_FRAME=1 restores the desktop frame
3	Closing the last window keeps tasks running	window-all-closed quits only on Windows now; the application and its Host stay alive, with a Show Window menu entry to get the window back
4	dsh command on PATH	New POSIX launcher plus a Linux branch of the command installer (~/.local/bin/dsh); an existing foreign command is reported and backed up, never silently overwritten
5	dsh:// deep links	Desktop entry carries MimeType=x-scheme-handler/dsh; the shell already registers the scheme
6	Bundled runtime	Runtime preparation selects the Linux payload (Node/pnpm/Python, Electron binary, native packages) by target platform instead of assuming macOS or Windows
7	Updates	Linux packages without a feed; set DSH_DESKTOP_LINUX_UPDATE_ORIGIN to opt into a self-hosted generic (AppImage) feed

Office document conversion works out of the box: Linux uses the bundled WASM LibreOffice engine (@deepseek-ai/libreoffice-kit-wasm), not a system LibreOffice.

2. Requirements and fixed paths

The build host must be Linux x86_64. The patch keeps upstream's rule that linux-x64 refuses to build anywhere else, so this cannot be cross-built from macOS. linux-arm64 is not part of this series.

Requirement	Value	Check
Host	Linux x86_64	uname -sm → Linux x86_64
Node	^22.19.0 || >=24.0.0	node -v
pnpm	11.7.0	corepack enable && pnpm -v
git	any recent	git --version
Free disk	≥ 15 GB (checkout ≈ 200 MB, dependencies + Electron + runtime payloads several GB)	df -h "$HOME"
Network	registry.npmjs.org, nodejs.org, Python standalone builds, github.com (Electron), electron-builder's own downloads	proxy-dependent; see triage
Display for the smoke run	X11/Wayland, or xvfb-run	echo "$DISPLAY$WAYLAND_DISPLAY"

Paths used throughout this document — set them first:

export PATCH_REPO="$HOME/src/deepseek-harness-linux-desktop"   # this repository
export SRC="$HOME/src/deepseek-harness"                        # upstream checkout (created below)
export TARGET_DIR="$SRC/apps/desktop/.desktop-build/targets/linux-x64"
export ARTIFACTS="$TARGET_DIR/artifacts"

3. Build — one-shot script

An agent can execute this block as-is (it aborts on the first failed assertion):

set -euo pipefail

# --- preflight -------------------------------------------------------------
[ "$(uname -s)" = "Linux" ] || { echo "FAIL: host is not Linux"; exit 1; }
[ "$(uname -m)" = "x86_64" ] || { echo "FAIL: host is not x86_64"; exit 1; }
command -v git >/dev/null || { echo "FAIL: git missing"; exit 1; }
command -v node >/dev/null || { echo "FAIL: node missing"; exit 1; }
corepack enable >/dev/null 2>&1 || true
[ "$(pnpm -v)" = "11.7.0" ] || echo "WARN: pnpm is $(pnpm -v), expected 11.7.0"

export PATCH_REPO="${PATCH_REPO:-$HOME/src/deepseek-harness-linux-desktop}"
export SRC="${SRC:-$HOME/src/deepseek-harness}"

# --- fetch the patch set and apply it --------------------------------------
[ -d "$PATCH_REPO/.git" ] || git clone https://github.com/lql341/deepseek-harness-linux-desktop.git "$PATCH_REPO"
sh "$PATCH_REPO/apply.sh" "$SRC"

# --- prove the patches landed ---------------------------------------------
[ "$(git -C "$SRC" rev-parse HEAD^{tree})" = "5103892b735d996d9180605f73e5477bc84a894f" ] \
  || { echo "FAIL: patched tree hash mismatch"; exit 1; }
[ -f "$SRC/apps/desktop/.env.linux" ] || { echo "FAIL: .env.linux missing"; exit 1; }

# --- dependencies ----------------------------------------------------------
cd "$SRC"
pnpm install --frozen-lockfile

# --- cheap preflight: validates .env.linux and the build toolchain ---------
pnpm --dir apps/desktop run check:package     # expect: "would publish 0.2.0-rc.2 ... valid"

# --- directory build first: does it even start? ----------------------------
pnpm --dir apps/desktop run package:linux:x64:dir

# --- real artifacts --------------------------------------------------------
pnpm --dir apps/desktop run package:linux:x64
ls -l "$SRC/apps/desktop/.desktop-build/targets/linux-x64/artifacts"

4. Build — step by step (with success conditions)

Step 0 — host preflight

uname -sm          # expect: Linux x86_64
node -v            # expect: v22.19+ or v24+
corepack enable && pnpm -v   # expect: 11.7.0
df -h "$HOME"      # expect: >= 15G available

If uname -m is aarch64, or uname -s is Darwin, stop: this patch set does not cover that combination. On macOS you can still apply the patches (step 1 works anywhere) but package:linux:x64 will refuse to run.

Step 1 — clone this repository and apply the series

git clone https://github.com/lql341/deepseek-harness-linux-desktop.git "$PATCH_REPO"
sh "$PATCH_REPO/apply.sh" "$SRC"

apply.sh clones upstream at tag dsh-v0.2.0-rc.2, creates branch linux-desktop, runs git am on all 12 patches, and copies .env.linux.example to .env.linux (the packaging code requires that file and aborts without it).

Success conditions — all four must hold:

git -C "$SRC" log --oneline | head -1
#   expect: "fix(desktop): declare the Linux installer config fields"
git -C "$SRC" rev-parse HEAD^{tree}
#   expect: 5103892b735d996d9180605f73e5477bc84a894f
git -C "$SRC" status --porcelain      # expect: empty
test -f "$SRC/apps/desktop/.env.linux" && echo env-ok

To review rather than trust: git -C "$SRC" log --stat shows the 5 topic commits.

Step 2 — install dependencies

cd "$SRC"
pnpm install --frozen-lockfile

Expect exit 0. Mirrors work if the default registry is slow — either set DSH_DESKTOP_NPM_REGISTRY in apps/desktop/.env.linux (used by the bundled runtime install), or ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ for the Electron download.

Step 3 — cheap preflight (no build, seconds)

pnpm --dir apps/desktop run check:package

This validates .env.linux, the release settings and the host toolchain, then prints something like desktop package: linux-x64 would publish 0.2.0-rc.2; local configuration and toolchain valid. Fix anything it reports before spending time on a real build — this is the cheapest place to catch a wrong pnpm, a missing .env.linux, or a bad entry in it.

Step 4 — directory build (the first real build)

pnpm --dir apps/desktop run package:linux:x64:dir

Every package command builds the whole repository itself, prepares the Electron distribution, installs the production runtime closure from the registry, and writes the unpacked application. Expect several minutes and a lot of output; exit 0 is the pass condition.

Success conditions:

ls -d "$ARTIFACTS"/linux-unpacked                                    # unpacked application
ls -l "$ARTIFACTS/linux-unpacked/DeepSeek Harness"                   # the Electron binary, executable

Step 5 — AppImage + deb

pnpm --dir apps/desktop run package:linux:x64
ls -l "$ARTIFACTS"/*.AppImage "$ARTIFACTS"/*.deb

Expect exactly two artifacts named from the product version (see §6). No signing or notarization runs for Linux, so nothing else is needed here.

Pass --build-version if you want your own numbering, e.g. pnpm --dir apps/desktop run package:linux:x64 -- --build-version 0.2.0-rc.2.linux.1; without it, artifacts carry the upstream product version.

Step 6 — smoke run

# Directory build, headless host:
xvfb-run -a "$ARTIFACTS/linux-unpacked/DeepSeek Harness"

# Or install the deb (also what makes the dsh command usable, see §9):
sudo apt install "$ARTIFACTS"/deepseek-harness-*-linux-amd64.deb
dpkg -L deepseek-harness | grep -E '/(bin|opt)/'    # find the installed executable
# then launch it from the desktop menu, or run the path printed above (quote it: it contains a space)

Things to watch in the first 30 seconds:

• it must reach the workspace/welcome UI and not print desktop policy: unsupported platform;
• the window should have no system titlebar and native controls at the top right (if the desktop environment draws something odd, retry with DSH_DESKTOP_LINUX_NATIVE_FRAME=1);
• in a container without user namespaces, Chromium's sandbox may refuse to start — prefer the deb, or add --no-sandbox only as a last resort (it lowers security).

5. Acceptance checklist (the 7 behaviours)

Run these in order; each one maps to a patch in patches/.

#	Check	Command / observation	Expected
1	Starts	launch as in step 6	workspace opens, no unsupported platform error
2	Window chrome	look at the window; toggle DSH_DESKTOP_LINUX_NATIVE_FRAME=1	overlay caption + native controls; env var restores the frame
3	Stays alive	close the last window, then pgrep -af "DeepSeek Harness"	process still running; Show Window menu item brings the window back; explicit Quit really exits
4	dsh on PATH	install the command from the app UI, then in a new shell: command -v dsh && dsh --version	~/.local/bin/dsh, runs the bundled CLI (ensure ~/.local/bin is on PATH)
5	Deep link	xdg-mime query default x-scheme-handler/dsh then xdg-open 'dsh://open'	a desktop file is registered and the window focuses
6	Runtime + Office	in a session run a shell tool; ask for a DOCX→PDF conversion	bash tool works (Landlock, kernel ≥ 5.13); conversion succeeds via the bundled WASM engine
7	Updates	launch with no DSH_DESKTOP_LINUX_UPDATE_ORIGIN	no update check; with a self-hosted generic feed origin set, the app reads latest-linux.yml

6. Artifacts and where they land

Everything is written under apps/desktop/.desktop-build/targets/linux-x64/:

Path	Contents
artifacts/linux-unpacked/	unpacked application (from :dir); executable DeepSeek Harness
artifacts/deepseek-harness-<version>-linux-x86_64.AppImage	AppImage
artifacts/deepseek-harness-<version>-linux-amd64.deb	Debian package
runtime/	prepared Electron + pnpm + launcher for this target
dsh/	the bundled dsh runtime tree that becomes app.asar/dsh
package-set/, downloads/	intermediate package set and downloaded archives
packaging-runs/	per-run logs and the release record

With the default version these are deepseek-harness-0.2.0-rc.2-linux-x86_64.AppImage and …-linux-amd64.deb.

7. Failure triage

Symptom	Cause	Action
desktop package: unsupported target "linux-x64"	patches not applied	re-run step 1; verify the tree hash
desktop package: cannot read …/.env.linux; copy …	required env file missing	cp apps/desktop/.env.linux.example apps/desktop/.env.linux
desktop package: linux-x64 requires a Linux x64 build host	building on macOS/arm64	build on Linux x86_64
desktop package: unsupported setting X in …/.env.linux	key not in the Linux template	use only DSH_DESKTOP_APP_ID, DSH_DESKTOP_NPM_REGISTRY, DSH_DESKTOP_LINUX_UPDATE_ORIGIN, the policy origins
ERR_PNPM_UNSUPPORTED_ENGINE / odd dependency errors	wrong Node or pnpm	Node ^22.19 || >=24, pnpm 11.7.0
Electron download timeouts / 404	proxy or mirror	ELECTRON_MIRROR, or export HTTPS_PROXY
missing required LibreOffice engine wasm	the WASM kit is absent from the runtime tree	confirm @deepseek-ai/libreoffice-kit-wasm installed (it is an optional dependency of @deepseek-ai/libreoffice-kit)
Type errors from tsc in main.ts	first real type check	report them; the policy-branch narrowing is the most likely spot
AppImage refuses to start (sandbox / user namespaces)	Ubuntu 23.10+ AppArmor restriction	install the deb, or add an AppArmor profile; --no-sandbox only as a last resort
dsh install refused with "transient AppImage mount"	AppImage resources live in a temporary mount	install the deb, or extract the AppImage and set DSH_DESKTOP_RESOURCES
Deep link does nothing	desktop file not registered	confirm xdg-mime query default x-scheme-handler/dsh; reinstall the deb

8. Verified / not verified

Verified:

• The series applies cleanly on dsh-v0.2.0-rc.2; after git am the resulting tree hash is 5103892b735d996d9180605f73e5477bc84a894f, with no leftover changes.
• apply.sh ran end to end under a C locale with no git identity configured: fresh shallow clone → 12 patches → .env.linux created → exit 0.
• Every changed file passes a syntax check; all native dependencies were resolved against the npm registry (Linux variants exist, node-pty ships linux-x64/arm64 prebuilds).
• check:package passed, and the official Linux build passed runtime preparation, Office document round-trip, and Electron packaging stages.
• The resulting artifacts were deepseek-harness-0.2.0-rc.2-linux-x86_64.AppImage and deepseek-harness-0.2.0-rc.2-linux-amd64.deb; the deb metadata and contents were inspected.
• The Linux installer uses the Debian-safe executable name deepseek-harness; its generated postinst registers that name with update-alternatives instead of using the display name, and removes the legacy /usr/bin/DeepSeek Harness symlink during upgrades.
• The deb installed successfully on Debian/Ubuntu via apt; dpkg reports install ok installed and /usr/bin/deepseek-harness resolves through the expected alternatives entry.
• The packaged application started successfully and exposed its local dsh web endpoint.
• GitHub Actions on ubuntu-24.04 (workflow Linux desktop verification, dispatch run 37000258154, 2026-10-02): clean clone → 12 patches → pnpm install --frozen-lockfile → pnpm run typecheck → apps/desktop build → check:package → package:linux:x64:dir → artifact inspection → headless runtime smoke → Xvfb GUI smoke → AppImage + deb → deb install/exercise/uninstall → AppImage boot → desktop suite baseline, every step green.
• The deb works end to end on the runner. apt-get install reports Status: install ok installed; update-alternatives points /usr/bin/deepseek-harness at /opt/DeepSeek Harness/deepseek-harness; xdg-mime query default x-scheme-handler/dsh answers deepseek-harness.desktop; the installed binary runs as Electron 44 / Node 24; resources/runtime/cli/bin/dsh --version prints 0.2.0-rc.2; the packaged command manager installs ~/.local/bin/dsh and dsh --version works from PATH; removal and apt-get remove both leave nothing behind. (patches/0010 is what makes the launcher reachable at all — before it, every run printed dsh: the … payload is missing.)
• The AppImage boots without FUSE. --appimage-extract-and-run (also the Ubuntu 23.10+ path) serves dsh web: http://127.0.0.1:<port> for the full 40 s window with no desktop policy: unsupported platform rejection; the artifact is an ELF 64-bit x86-64 executable.
• Desktop suite baseline on Linux: 123 of 128 files pass (1357 tests passed, 58 skipped). The single failing file is apps/desktop/tests/macos-notarization-proxy.spec.ts, which guards a macOS-only feature (proxy recovery requires macOS) and whose flock helper is not built on Linux. The two other files that failed before — cli-launcher.spec.ts (our launcher regression, fixed by patches/0010) and desktop-upload-plan.spec.ts (patches/0011) — now pass.
• Upstream's own Linux gate, pnpm run check:ci:linux-primary (run 37042752808, serial and with Playwright browsers): 78 of 80 gates pass on the patched tree, against 79 of 80 on the unpatched base tag under identical settings. Neither remaining failure is ours: web browser snapshot fails the same way on the unpatched tag on this runner (the browsers install, the runner lacks their system libraries), and one flaky test in scripts/persistence-schema.spec.ts — a file the series never touches — passed on the base-tag run and varied 0/1/8 failures across runs. patches/0012 fixed the two gate failures that were ours: four oxlint style errors and a commit-hash reference that verify-repository-references rejects.
• Sandbox confinement on a real kernel: the bwrap leg (2 files) and the Landlock leg (2 files) both pass, and each leg is asserted to have run rather than self-skipped — the Landlock files force the bwrap rung off, so each proves exactly one mechanism.
• A keyless agent turn: apps/cli/tests/profiles/headless/tests/keyless-smoke.e2e.ts boots the real Loader tree with no API key, runs the production bash tool, asserts the tool/call → tool/result round trip (CLI_TOOL_ROUND_TRIP) and that the turn is persisted as zstd JSONL. Together with scripts/smoke-runtime.ts this covers the toolchain on Linux: PTY, FFI (koffi), sharp, ripgrep, glob, the bundled pnpm and Python, and real DOCX/XLSX/PPTX→PDF conversion through the bundled Office engine with PATH emptied.
• The first real Linux typecheck failed the whole repository (pnpm run typecheck, exit 2) on apps/desktop/tests/installer-packaging.spec.ts with three TS2339s — Property 'linux' and Property 'deb' do not exist on DesktopElectronBuilderConfig. The hand-written declaration in electron-builder.config.d.mts was never extended for the Linux target; patches/0009 fixes it and the typecheck then passes.
• The bundled runtime answers from inside the archive: ELECTRON_RUN_AS_NODE=1 <launcher> --expose-internals resources/app.asar/dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/cli.js --version prints 0.2.0-rc.2 and exits 0. The payload lives inside app.asar; asarUnpack holds only the .node/.so binaries, ripgrep, the libreoffice kit and the Landlock launcher, so a shell test on that path can never succeed.
• The Linux native set is complete in the unpacked tree (node-pty, sharp-linux, koffi-linux, ripgrep-linux, node-addon-system-linux, sherpa-onnx-linux, libreoffice-kit-wasm) and there are no darwin/win32 leftovers outside resources/runtime/pnpm. That directory is a verbatim copy of the published pnpm package and carries the same cross-platform vendored helpers in the shipped macOS build.
• Under Xvfb the shell boots and serves its local endpoint (dsh web: http://127.0.0.1:<port>) with no desktop policy: unsupported platform rejection.
• A real desktop session (ci/desktop-session.sh, run 37089025040; Xvfb + openbox + a session bus, driving the installed deb): the window is created and mapped (DeepSeek Harness, 1288x824), closing the last window does not end the application, x-scheme-handler/dsh resolves to the package's deepseek-harness.desktop, and activating that entry with dsh://open brings the window back; a later launch is routed to the running instance instead of starting a second one.
• Debian 13 (trixie), runs 37091835014 and 37094351188 — every step green. Inside a debian:13 container the job bootstraps Node 24 and pnpm 11.7.0 from source, applies the series, installs the workspace, typechecks, runs the packaging preflight, builds the directory target, smokes the bundled runtime, builds the deb and the AppImage, installs the deb with apt (Status: install ok installed; /usr/bin/deepseek-harness through update-alternatives), resolves dsh:// to deepseek-harness.desktop, runs the installed binary as Electron 44 / Node 24, installs and removes ~/.local/bin/dsh through the packaged command manager (dsh --version → 0.2.0-rc.2), drives the same desktop session as Ubuntu (window mapped, closing it does not end the application, a dsh:// activation brings it back, a later launch is routed to the running instance), uninstalls cleanly, and boots the AppImage with --appimage-extract-and-run for the full 40 s window with no desktop policy: unsupported platform.
• The deb upgrade path and the hardened-kernel launch (run 37095694923). Installing v0.2.0-rc.2-linux.1 and then …-linux.2 on top of it removes a legacy /usr/bin/DeepSeek Harness link while update-alternatives keeps resolving /usr/bin/deepseek-harness. With kernel.apparmor_restrict_unprivileged_userns=1 — what Ubuntu 23.10+ does, and the reason an AppImage can refuse to start there — the package installs /etc/apparmor.d/deepseek-harness and the application still starts and passes the whole session check without --no-sandbox (chrome-sandbox stays 0755; the profile carries the sandbox).
• Wayland (run 37135502569). With a headless Weston compositor and --ozone-platform=wayland, the published deb boots as a pure Wayland client (no X server) and serves its local endpoint, with no desktop policy: unsupported platform. The DRM render-node and wl_seat warnings in the log come from the headless compositor having no GPU and no input devices, not from the application.

Not verified in this environment:

• Electron's titleBarOverlay appearance per desktop environment; window drag/resize and caption sizing in both themes.
• Desktop integration itself (tray, notifications, window controls in a real session); the suite above covers the packaged runtime, not a running desktop.

9. Known limits

• Not achievable 1:1: macOS traffic-light buttons, sidebar vibrancy, Dock bounce. The patch set substitutes native overlay window controls, a flat sidebar, and notifications.
• The dsh command requires the deb: an AppImage's resources live in a transient mount, so installing a command from it is refused with an actionable message (DSH_DESKTOP_RESOURCES is the escape hatch for an extracted tree).
• Platform identity: a Linux build reports the macOS desktop identity to DeepSeek Platform, because the shared account package only defines darwin/win32 for x-client-platform (omitting it degrades to web).
• Mandatory-update policy is inert on Linux (there is no official Linux feed).
• Only linux-x64; linux-arm64 is not part of this series.
• The welcome window's caption colour follows the system palette only at creation.
• The deb maintainer field is a placeholder (DeepSeek Harness).
• A second close/restore cycle does not bring the window back. Closing the last window keeps the application and its Host running (by design), and the first later activation or launch restores the window. Close it a second time, however, and the process keeps serving with nothing on screen: ci/desktop-session.sh shows only the 10x10 tray helper window while the Host endpoint still answers. Found in CI run 37089025040; an attempted fix was withdrawn because it did not change the behaviour.
• Two checks cannot run inside the Debian container job. Docker's default seccomp profile denies unshare, so the bwrap sandbox leg self-skips there (the Landlock leg runs strictly) and the keyless agent smoke fails while reading its own session directory (ENOENT …/.sessions) without surfacing the driver's stderr, so it is reported rather than gated. Both run strictly on the Ubuntu runner, where the kernel allows the namespaces they need.

10. Layout, license, attribution

patches/0001..0012*.patch   git format-patch series, applied in file-name order
apply.sh                    clone upstream at the base tag, apply the series, create .env.linux
LINUX-DESKTOP.md            long-form guide: per-file notes, verified facts, open items
LICENSE                     MIT (upstream DeepSeek + this patch set)

Each patch is one topic: (1) accept the target, (2) install the dsh command, (3) prepare the Linux runtime payload, (4) macOS-like shell behaviour, (5) documentation, (6) packaging type declarations, (7) Debian-safe executable naming, and (8) legacy launcher cleanup during upgrades.

This patch set is distributed under the MIT License (see LICENSE). The patches are diffs against deepseek-ai/deepseek-harness, which is MIT-licensed, Copyright (c) 2026 DeepSeek; that notice is retained here.

Not affiliated with, endorsed by, or supported by DeepSeek. Upstream is in developer preview and iterates quickly, so expect conflicts when rebasing onto newer tags.