WorkBuddy ships no Linux build for its international edition — and that is
the edition you need if you cannot log in with a Chinese phone number. This
toolchain converts an official WorkBuddy macOS build that you supply — a
China-channel .dmg or an international-channel .zip — into a native Linux
application, then packages it as .deb (Ubuntu, Debian, Linux Mint, Pop!_OS),
.rpm (Fedora, RHEL, openSUSE) or .pkg.tar.zst (Arch, Manjaro).
No Wine. No virtual machine. No repackaged installer to trust: you run the converter on your own machine, against an archive you downloaded from Tencent yourself.
Check the official channel first. The China edition does now publish Linux packages —
5.6.2.40046327, as x86_64.deb, x86_64.rpmand arm64.deb— so on Ubuntu/Debian/Fedora with a Chinese account you should install theirs, not this. They are China-edition only: the international CDN has no Linux artifact at all. See docs/upstream-linux-builds.md for the verified URLs, sizes and control metadata.
A maintained fork of JipZeonGit/workbuddy-linux
(MIT). The approach is unchanged — this fork fixes the ways it used to fail
silently, and adds support for the international edition. See
CHANGELOG.md and IMPROVEMENTS.md.
This repository contains no Tencent software. It is a converter, not a distribution channel. You download the archive from Tencent yourself; nothing is redistributed here. Generated artifacts are gitignored and stay local.
- Is this for you?
- Install from a release
- How it works
- Requirements
- Quick start
- Accounts and regions
- Environment variables
- Troubleshooting
- FAQ
- Known limitations
- Security
- Legal
- 简体中文
This is the right project if you searched for any of these:
- run WorkBuddy on Ubuntu / Debian / Fedora / Arch Linux
- WorkBuddy Linux download — the China edition has official
.deb/.rpmpackages now; the international edition still has no Linux build at all - convert a macOS
.dmgto a.deb— specifically an Electron/VS Code app - WorkBuddy login without a Chinese phone number — see accounts and regions
- WorkBuddy "no window" / blank window on Linux — that is the
E2BIGbug this fork fixes - Electron
MAX_ARG_STRLEN/execve E2BIGon Linux - libayatana-appindicator tray menu empty in an Electron app
- Wayland vs X11 ozone platform for a repackaged Electron app
It is not for you if you want a prebuilt installer from a stranger, if you are on ARM/aarch64, or if you need Tencent support to help with the result.
Releases carry the toolchain, not a converted application — the converted
payload is Tencent's proprietary app.asar, so it is built on your machine.
# 1. fetch the bootstrap
curl -fsSLO https://github.com/mhzsajan/workbuddy-linux/releases/latest/download/install-workbuddy.sh
chmod +x install-workbuddy.sh
# 2. run it, pointing at the official archive you downloaded
./install-workbuddy.sh ~/Downloads/WorkBuddy.dmg # or WorkBuddy-*.zipThe bootstrap verifies the download against the release's SHA256SUMS, unpacks
the toolchain to ~/.local/share/workbuddy-linux, and hands over to the
converter. --toolchain-only stops before building.
Each release's notes are the matching CHANGELOG.md section.
WorkBuddy is an Electron/VS Code application, and its app.asar JavaScript is
platform-neutral. So only the binary layer needs replacing:
- Extract the archive (7-Zip for
.dmg,unzipfor.zip). - Read the Electron version out of the bundle's
Info.plist. - Download the matching Linux x86_64 Electron runtime.
- Copy
app.asar+app.asar.unpackedinto the new app directory. - Recompile the native modules (
node-pty,better-sqlite3, …) against Linux Electron headers — the macOS.nodebinaries cannot load on Linux. - Patch
app.asarfor the Linux-specific failures below. - Generate a launcher, desktop entry and icon, then package.
| Patch | Symptom it fixes |
|---|---|
process.env shim |
A ~260 KB config string in an env var exceeds Linux's 128 KB MAX_ARG_STRLEN, so every execve() fails with E2BIG and no window ever appears |
| Tray context menu | libayatana-appindicator never emits click, so the tray menu is empty unless setContextMenu() is called explicitly |
| Tray icon path | The AppIndicator backend cannot read an in-memory NativeImage, so the tray shows a broken-image placeholder; an on-disk PNG is used instead |
| Sidecar spawn | Large env entries are spilled to temp files before spawning |
The env shim is mandatory. The tray and window-frame patches are cosmetic, so a payload newer than their anchors degrades to a warning instead of a failed build — the window still opens.
| Requirement | Notes |
|---|---|
| Architecture | x86_64 only — the toolchain downloads an x86_64 Electron runtime |
| 7-Zip | Version ≥ 21, DMG input only. ZIP input uses unzip and needs no 7-Zip |
| Node.js | ≥ 20 (installed by make deps if your distro's is older) |
| Disk | ~4 GB free |
| Input | An official WorkBuddy .dmg (China channel) or .zip (international channel), or an extracted .app |
Tested package managers: apt, dnf5/dnf, pacman, zypper.
Ubuntu 22.04 note: the
7zippackage only exists from 24.04 onwards, and 22.04'sp7zipis too old.make depsdetects this and tells you how to install the official static build. 24.04+ is the supported path.
git clone https://github.com/mhzsajan/workbuddy-linux
cd workbuddy-linux
make deps # system packages + Node 20+
mkdir -p downloads # download the macOS archive from Tencent
# put exactly ONE .dmg or .zip in here
make preflight # arch, disk, 7-Zip, Node, input sanity
make build-app # extract, swap runtime, rebuild natives, patch
make run-app # test before packaging anything
make package # .deb / .rpm / .pkg.tar.zst into dist/
make install # dpkg -i + dependency repairPrefer to point at a file directly?
make build-app DMG=/home/you/Downloads/WorkBuddy.dmg
make build-app DMG=/home/you/Downloads/WorkBuddy-darwin-x64-5.9.4.zipWorkBuddy has two editions with separate account systems, and the edition you install decides whether you can log in at all:
| China edition | International edition | |
|---|---|---|
| Login | phone (SMS) / WeChat | Google, GitHub OAuth |
| Needs a +86 number | yes | no |
| Official desktop build for Linux | published (.deb) |
none |
| Convertible with this toolchain | yes (.dmg) |
yes (.zip) |
If you are outside mainland China and have no +86 number, the China .deb is
unusable — and Tencent publishes no international Linux desktop build. Its
international channel still advertises a Linux entry, but the artifact behind
it is a stale 5.5.2 that returns 404; macOS and Windows are on 5.9.4.
You can still get the international desktop app on Linux by converting
Tencent's international macOS .zip with this toolchain:
./install.sh --fresh downloads/WorkBuddy-darwin-x64-5.9.4.42593613.zipVerified working against 5.9.4 (Electron 37.10.3): the app fetches its config
from www.workbuddy.ai and emits an international login URL that you can
complete in a browser on any machine. At this version the UI patch anchors no
longer match, so the build runs the env shim only — the window opens, but the
tray menu/icon are unpatched.
Alternatively the CLI offers the same international login:
npm install -g @tencent-ai/codebuddy-code
codebuddy --serve --host 127.0.0.1 --port 7788 # prints a password-protected URLDo not try to repoint the China build's auth endpoint at www.workbuddy.ai —
tokens are region-bound (authStateReplication: "regional") and the trusted
origins are a fixed .cn allowlist, so it cannot work.
Full evidence, API responses and the SSH port-forward recipe: docs/account-and-region.md.
| Variable | Default | Effect |
|---|---|---|
WB_ALLOW_UNPATCHED |
0 |
1 lets the build continue when patching fails. The result will almost certainly show no window. |
WB_NO_SANDBOX |
1 |
0 re-enables Electron's Chromium sandbox (needs unprivileged user namespaces). |
WB_KEEP_FOREIGN_PLATFORM |
0 |
1 keeps the darwin-* / win32-* payload. Only useful for debugging; it adds ~297 MB of binaries that cannot run. |
WORKBUDDY_INSTALL_DIR |
./workbuddy-app |
Where the converted app is assembled. |
ELECTRON_VERSION |
auto-detected | Force a runtime version if detection falls back. |
ELECTRON_MIRROR |
— | Mirror for the Electron runtime download. Falls back to npmmirror automatically. |
ELECTRON_HEADERS_URL |
— | Headers dist URL used for native rebuilds. |
| Symptom | Cause | Fix |
|---|---|---|
| Build says patches failed, exit 2, 3 or 6 | The archive could not be read, unpacked or repacked | Check the input is a complete download; re-run |
| App starts but no window | app.asar was not patched |
Check asarPatched in .workbuddy-linux/build-info.json |
Missing X server or $DISPLAY |
--ozone-platform-hint=auto chose X11 on a Wayland-only session |
Launch with ./workbuddy-app/start.sh --ozone-platform=wayland (the generated launcher now detects this) |
make deps fails on 7-Zip |
Ubuntu 22.04 has no 7zip package |
Install the static build, see above |
dpkg leaves the package unconfigured |
Missing dependencies | sudo apt-get install -f (now run automatically by make install) |
| Blank window on Wayland | GPU/compositing issue | ./workbuddy-app/start.sh --disable-gpu |
| Tray icon is a broken image | Icon PNG not written, or UI patches skipped | Verify workbuddy-app/.workbuddy-linux/workbuddy.png exists |
Can I run WorkBuddy on Linux without this?
Only if you accept Tencent's China-channel .deb, which requires a +86 phone
number to log in. There is no official international Linux desktop build.
Does this download WorkBuddy for me? No, by design. You download the official macOS archive from Tencent; this converter only rearranges what you already have. That is also why releases do not contain an installer.
Which distros work?
Anything with x86_64 and a package manager among apt, dnf, pacman,
zypper. Ubuntu 24.04+ is the best-tested path. ARM is not supported — the
toolchain fetches an x86_64 Electron runtime.
Why does the build stop with "patches failed"? Older versions aborted whenever an anchor string moved. Now only the env shim is mandatory; if the tray/window anchors are missing you get a warning and a working window without a tray menu. A hard failure means the archive itself could not be read or repacked.
Can I use an international account without a Chinese phone number?
Yes — convert the international .zip, or use the codebuddy CLI with
Log in via International Site. Details in
docs/account-and-region.md.
Will it auto-update?
No. Upstream relies on macOS ShipIt / Windows Squirrel. Re-run the pipeline with
a newer archive. The converted app's own update check is pointed at Tencent's
Linux feed, which returns 204 and does nothing.
How do I uninstall?
Remove the package (sudo apt remove workbuddy) and delete
~/.workbuddy-ai (international) or ~/.workbuddy (China edition).
Is this legal? It is a converter you run locally, and nothing is redistributed here. Converting a macOS-licensed application to run on another OS may conflict with WorkBuddy's EULA — that decision is yours. Do not report conversion problems to Tencent support.
These come from upstream and are not fixed by this fork:
- Tencent Docs engine removed —
@tencent/docs-engineand@tencent/tencent-docs-ai-engineship macOS-only binaries (in 5.9.4 the engine's entirebin/is a 233 MBdarwin-x64tree), which woulddlopen-crash on Linux. The prune step deletes that payload rather than shipping dead weight. - AI code sandbox degraded — Tencent's proprietary
vendor/sandboxhas no Linux build, so code execution falls back to an unsandboxed terminal or is refused. - No auto-update — see the FAQ.
- Patch anchors are exact strings. The patcher matches minified upstream code. It now fails loudly when a required anchor is missing instead of producing a broken app, but it still cannot patch a structurally different version.
- The tray icon does not appear on 5.9.4. All three tray/window anchors are absent from that build, so those cosmetic patches are skipped by design.
What was actually run, on what hardware, with which outputs: docs/verification.md.
The generated launcher runs Electron with --no-sandbox by default, because
upstream does not ship a SUID sandbox helper. That disables the Chromium
renderer sandbox, while the application can execute AI-generated commands.
Combined with the missing code sandbox above, treat this as running untrusted
code with your user privileges. Use a VM or container if that matters.
- Not affiliated with, endorsed by, or supported by Tencent.
- No Tencent binaries are stored or redistributed by this repository. You supply the archive; all generated artifacts stay on your machine.
- Converting a macOS-licensed application to run on another OS may conflict with WorkBuddy's EULA. That decision is yours.
- Do not report problems from this conversion to Tencent support.
JipZeonGit/workbuddy-linux— the upstream this forks fromJipZeonGit/codebuddy-ide-cn-linux— the same author's CodeBuddy IDE port; its AUR and AppImage packaging are worth readingelectron/electron— the runtime the payload is rehosted onelectron/asar— used to unpack and repackapp.asar
This repository previously held an unrelated desktop agent application. That code is still reachable in the git history; the current tree is the Linux conversion toolchain only.
WorkBuddy 没有 Linux 桌面版。 本项目把你自行下载的官方 macOS 安装包（国内版
.dmg / 国际版 .zip）转换成可在 Linux 运行的原生应用，并打包为
.deb / .rpm / .pkg.tar.zst。不用 Wine，不用虚拟机，也不分发任何腾讯二进制文件。
与上游相比，主要修复的是失败被静默吞掉的问题：补丁失败以前只打印一行警告 然后继续，最终得到一个「启动后没有窗口」的包；现在会直接中止构建并说明原因。 完整改动见 CHANGELOG.md 与 IMPROVEMENTS.md。
git clone https://github.com/mhzsajan/workbuddy-linux
cd workbuddy-linux
make deps
mkdir -p downloads # 放入唯一一份官方 macOS .dmg 或 .zip
make preflight
make build-app
make run-app
make package && make installWorkBuddy 分国内版与国际版，两个账号体系互不通用：国内版用手机号/微信登录，
国际版用 Google / GitHub 登录。国内版 .deb 只认 +86 手机号；而国际版没有发布
Linux 桌面版（官方更新接口里 Linux 条目停留在 5.5.2，实际文件已 404，macOS /
Windows 已到 5.9.4）。
在 Linux 上要使用国际版账号，可以转换国际版 macOS .zip，或改用 CLI：
npm install -g @tencent-ai/codebuddy-code
codebuddy --serve --host 127.0.0.1 --port 7788首次启动的登录方式选择界面里选 Log in via International Site 即可。详细证据与 远程端口转发方法见 docs/account-and-region.md。
本仓库不分发任何腾讯二进制文件，仅作为转换工具。由此产生的任何问题请勿反馈给 官方客服。