arboretum/packages/desktop

Arboretum Desktop

Native desktop shell (Electron) for Arboretum. It runs the existing daemon as a child process and shows its web UI in a window, already authenticated (no login screen). The heavy lifting stays in the daemon; this package is a thin shell (window lifecycle, daemon supervision, auto auth).

This package is intentionally outside the root npm workspaces so the daemon CI stays light. It has its own package-lock.json and is built on a developer machine (or a dedicated CI runner), not by the main npm run build.

How it works

1. The shell picks a data directory under the OS user-data path and spawns the bundled Node runtime running the packaged daemon (build/server/package/dist/index.js) with ARBORETUM_EMIT_TOKEN_FD=3.
2. The daemon mints a fresh token and writes {token, url} on file descriptor 3 (private stdio pipe).
3. The shell posts that token to /api/v1/auth/login from the window's session (server to server), which drops the arb_session cookie into the session jar, then loads the SPA on 127.0.0.1.
4. On quit, the daemon child is asked to stop (SIGTERM on POSIX, taskkill /T on Windows, which Windows requires to take the whole process tree down rather than leaving PTY grandchildren behind).

A standalone Node runtime (pinned, >= 22.16) is bundled instead of reusing Electron's Node, so node:sqlite works without a flag and the node-pty prebuild keeps the node. ABI prefix.

Prerequisites (all platforms)

• Node >= 22.16 to build.
• git on PATH at runtime (worktree operations). claude is discovered on PATH or via the in-app Claude CLI setting; it is not bundled.

Develop

cd packages/desktop
npm install            # ELECTRON_SKIP_BINARY_DOWNLOAD=1 to skip the Electron binary if you only typecheck
npm run dev            # bundles main/preload, then `electron .` against the repo's built daemon

npm run dev runs the daemon from the repo (packages/server/dist, so run npm run build at the repo root first) using the system node.

Build installers

Each command builds the shell, prepares the daemon (npm pack + runtime deps with the right node-pty prebuild) and a standalone Node runtime, then runs electron-builder.

npm run dist:linux     # AppImage + .deb  (on Linux)
npm run dist:win       # NSIS + portable  (on Windows)
npm run dist:mac       # dmg + zip        (on macOS)

Artifacts land in packages/desktop/release/.

Linux

Fully supported. dist:linux runs on a Linux host or the Gitea CI runner.

Windows

Must be built on a Windows host. Cross-building from Linux (including via Wine) does not work, and the option has been removed from this document to stop people losing time on it:

• node-pty's check-prebuild.js exits successfully as soon as the host binary exists, so prebuild-install never runs and no win32 binary is fetched (its published tarball only ships prebuilds/linux-*);
• its post-install.js copies conpty.dll and OpenConsole.exe only when the build platform is win32. Without them there is no ConPTY, hence no terminal at all.

In CI this is a dedicated job on a windows-latest runner, enabled by the ENABLE_WINDOWS_BUILD repository variable. Full procedure to register such a runner: docs/CI_RUNNERS.md.

The app requires Windows 10 1809+ (ConPTY). The installer is not code-signed, so SmartScreen shows "unknown publisher": choose "More info" then "Run anyway".

macOS (best-effort)

Build on a Mac (dmg/zip cannot be produced elsewhere); there is no macOS runner, so it is a manual step. The app is not signed or notarized, so Gatekeeper blocks the first launch: right-click the app then "Open", or run xattr -dr com.apple.quarantine /Applications/Arboretum.app.

What the shell adds beyond the window

• Tray icon (src/main/tray.ts): open the window, toggle launch-at-login, quit. On macOS it uses a monochrome template image so it follows the menu-bar theme.
• Application menu (src/main/app-menu.ts): required on macOS, where without it ⌘C / ⌘V / ⌘A are not bound anywhere in the app. Closing the window hides it; app.on('activate') brings it back from the Dock.
• Launch at login (src/main/autostart.ts): a .desktop file under ~/.config/autostart on Linux, app.setLoginItemSettings on Windows/macOS.
• Auto-update (src/main/updater.ts): see below.
• PATH enrichment (src/main/env.ts): a GUI app starts with a minimal PATH. On POSIX we add /usr/local/bin, /opt/homebrew/bin, ~/.local/bin; on Windows %LOCALAPPDATA%\Programs and %APPDATA%\npm, where the Claude CLI and global npm binaries actually live.

Auto-update

electron-builder emits latest*.yml next to the artifacts and electron-updater reads them from a floating desktop-latest release on Gitea, which the release workflow recreates on every version (that URL is baked into shipped binaries, so it must always exist). Auto-update covers Windows (NSIS) and Linux (AppImage); macOS updates are manual while the app is unsigned.

Bundled Node runtime

scripts/fetch-node.mjs downloads a pinned Node (SHA256 verified) and prunes it to the binary and its licence: headers, docs and npm/corepack are removed, since the daemon's dependencies are installed at build time, never at runtime. That takes the embedded runtime from ~205 MB to ~118 MB.

Icons

Generated by python3 brand/build-assets.py from the source logo, into resources/:

• icons/{16,24,32,48,64,128,256,512}x*.png : the Linux set, at standard hicolor sizes. This is not cosmetic: with a single non-standard size (the old 895×895), the directory is not declared in hicolor/index.theme and the freedesktop spec makes desktops ignore it, so the launcher showed no icon at all.
• icon.png (1024) : macOS source and generic fallback.
• icon.ico : Windows (NSIS installer and window).
• trayTemplate.png (+@2x) : monochrome macOS menu-bar icon.