Let Local Computer run on Windows and Linux, and install missing parts from the card

[DoodleBears]

Requested by Vain · project thread

Closes #1632 · claim: #1632 (comment) · task claude/cloud/session_017HT2wLfpGDvY1o5pMDusbE

Why: the product pack pins every Host to Local Computer, but Local only ran on macOS, so a Linux server or a Windows PC opened the panel to Mac instructions, "Needs attention" and a disabled button. And when a part was missing, the Human had to go to a terminal with no idea how long anything would take.

Change outline

1. Local Computer on three platforms

Before: on a non-Mac Host the probe reported unavailable, the Check permissions button was disabled, and ensure() threw "requires a macOS DSH Host".

After: Check permissions works on macOS, Windows and Linux. Upstream cua-driver-rs 0.31.0 ships all three; we pin one build per Host:

Host	Asset	Kept files	Ready when
macOS (any arch)	darwin-universal-binary.tar.gz	unchanged	Accessibility + Screen Recording
Linux x64 / arm64	linux-{x86_64,arm64}-binary.tar.gz	cua-driver	X11 or Wayland reachable
Windows x64 / arm64	windows-{x86_64,arm64}-binary.zip	cua-driver.exe, cua-driver-uia.exe	always (UIA needs no grant)

Archive SHA-256 values match upstream checksums.txt; every kept file is also checked before each launch. Other Hosts (e.g. linux-ia32) are refused before download. DISPLAY, WAYLAND_DISPLAY, XAUTHORITY, XDG_RUNTIME_DIR, XDG_SESSION_TYPE and DBUS_SESSION_BUS_ADDRESS are passed through to the driver.

Linux has three display cases, and in all of them the Bot can click and type, not only read the screen:

Host	What Local Computer does
Desktop session (Wayland, or X11 with XDG_CURRENT_DESKTOP / DESKTOP_SESSION)	Uses it as is.
DISPLAY points at a bare X server, e.g. the server Xvfb :99 the Bot Browser already uses	Shares that display; nothing new is started for the screen. It starts a window manager there (Chromium needs _NET_ACTIVE_WINDOW for foreground input) unless one already runs, plus a D-Bus session if none is set. Both stop with the driver.
No display	Starts a private desktop: Xvfb -displayfd (picks a free display), a D-Bus session (so AT-SPI trees are populated) and the first window manager found (openbox, xfwm4, …). Closing the driver stops all three.

A missing Xvfb or window manager shows up as missing packages on the card (section 2).

Real driver, no DISPLAY: download + checksum, Xvfb + openbox + D-Bus, readiness x11=true atspi=true, then click and type_text into Chromium:

``

Real driver, DISPLAY set to an existing bare Xvfb with Chromium already open (the validation-server layout): Local Computer added openbox on that display, then click and type_text landed:

```

2. Missing parts: install from the card, with progress

One shared card (packages/client/src/client/missing-packages.tsx) and one apt installer (packages/core/src/system/system-packages.ts) serve Computer and the Bot Browser.

• Things we download (the cua-driver, ~32 MB): a progress bar with MB counts.
• System packages (Linux desktop packages for Computer, Chrome's system libraries for Browser): when DSH runs as root or has passwordless sudo, an Install button runs apt-get update + install --no-install-recommends with live progress from APT::Status-Fd, then re-checks (Computer) or reopens the browser (Browser). Otherwise the card shows the sudo apt install … command with a Copy command button; Computer notices the packages appear and re-checks on its own.
• Install routes only accept packages from a fixed allow-list (desktop packages / known Chrome library packages), and require authorize: true.

Real DSH 0.2.0-rc.2 on Linux, Settings → Bot settings → Computer (captured on head ca141d0):

Download	Missing parts	Installing	Done
````	`````	``````	```````

Without administrator rights (status response's install forced to none in the browser; the package was then installed by hand in a shell and the card flipped to Granted by itself):

````````

Before (main): the Local card on Linux showed Mac copy, "Needs attention" and a disabled Check permissions button, with no install path.

3. Copy and docs

Panel copy (zh/en) and model guidance no longer say "Mac". ADR-0082 gains a "Linux and Windows delivery" section; CONTEXT and the living architecture are updated; changelog fragment added.

Other: ComputerRuntimeRunner.run takes an optional env, so doctor no longer goes through env (absent on Windows); check_permissions gets {prompt:false} only on macOS.

Special things to note

• Merge risk: medium, reversible by revert. Blast radius: the Local Computer target and the Browser missing-library notice; Container Computer is untouched. Review focus: (1) the install routes run apt-get as root/sudo, so check the allow-lists and the authorize gate; (2) on a server whose Xvfb is shared with the Bot Browser, Local Computer now runs openbox on that display while the driver is up, so Bot Browser windows there get title bars; (3) the Windows path is unverified on a real Windows Host (zip extraction relies on Windows 10+ tar.exe; readiness shape read from upstream source); (4) the Browser card is covered by jsdom tests only, not captured in a real Host; (5) the managed Linux desktop has no viewer yet.
• Merge order agreed with the long-run validation thread: Let full access use the Bot Browser and Computer without an approval card #1628 (merged), then this PR, then the browser screencast work for Bot Browser panel refreshes once per second; stream frames instead #1636. main is merged in; the only shared file with Bot Browser panel refreshes once per second; stream frames instead #1636 is the built packages/browser/lib bundle.
• A parallel Mac-built version of Local Computer should work on Linux and Windows Hosts, not only macOS #1632 (unpushed claude/local-computer-all-platforms, e11c89d3) reached the same design: same 0.31.0 per-platform pins, display-variable pass-through and X11/Wayland readiness. It will not get its own PR; its validation-server run is recorded below.

Verification

• pnpm lint, pnpm format:check, pnpm typecheck, pnpm changelog:check: pass
• vitest packages/computer packages/browser packages/core/test/system-packages.test.ts: 627 passed, 9 skipped
• Real Linux runs above: driver actions on a private Xvfb and on a pre-existing shared Xvfb, and the card flow (download → missing → one-click install → granted; manual install → auto re-check)
• Validation server, from the parallel Mac-built version (same driver build and readiness rule): Ubuntu 24.04-class, 2 cores, 3.6 GB, X11 via Xvfb, no Wayland. A test Host with DISPLAY=:98 downloaded and verified the Linux x86_64 driver, connected with 62 tools, and passed the permission check. The bare upstream binary detected :99 at 1440x900 and captured the full desktop.

🤖 Generated with Claude Code

https://claude.ai/code/session_017HT2wLfpGDvY1o5pMDusbE

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 22 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 1ca80d0c-9882-490a-aff4-395cde8cfbdb

📥 Commits

Reviewing files that changed from the base of the PR and between 37bff52 and cecb45b.

⛔ Files ignored due to path filters: 9

• docs/assets/pr/1632-local-computer-linux/card-0-downloading.png is excluded by !**/*.png
• docs/assets/pr/1632-local-computer-linux/card-1-missing-install.png is excluded by !**/*.png
• docs/assets/pr/1632-local-computer-linux/card-2-installing.png is excluded by !**/*.png
• docs/assets/pr/1632-local-computer-linux/card-3-granted.png is excluded by !**/*.png
• docs/assets/pr/1632-local-computer-linux/card-4-needs-password.png is excluded by !**/*.png
• docs/assets/pr/1632-local-computer-linux/linux-xvfb-typed.png is excluded by !**/*.png
• docs/assets/pr/1632-local-computer-linux/shared-display-typed.png is excluded by !**/*.png
• packages/browser/lib/client.js.map is excluded by !**/*.map
• packages/computer/lib/client.js.map is excluded by !**/*.map

📒 Files selected for processing: 28

• CONTEXT.md
• CONTEXT.zh.md
• changes/1632-local-computer-linux-windows.md
• docs/adr/0082-computer-target-is-profile-scoped-local-by-default.md
• docs/architecture/botharness-architecture.md
• packages/browser/lib/client.js
• packages/browser/src/client/browser-failure.tsx
• packages/browser/src/client/index.tsx
• packages/browser/src/client/locale.ts
• packages/browser/src/index.ts
• packages/browser/src/runtime/provision.ts
• packages/browser/test/client-failure.test.ts
• packages/browser/test/provision.test.ts
• packages/client/src/client/missing-packages.tsx
• packages/computer/lib/client.js
• packages/computer/src/client/local-computer.tsx
• packages/computer/src/client/locale.ts
• packages/computer/src/index.ts
• packages/computer/src/provider.ts
• packages/computer/src/providers/local.ts
• packages/computer/src/tool/catalog.ts
• packages/computer/src/tool/driver.ts
• packages/computer/src/tool/local-display.ts
• packages/computer/src/tool/local-driver.ts
• packages/computer/test/local-computer.test.ts
• packages/computer/test/local-display.test.ts
• packages/core/src/system/system-packages.ts
• packages/core/test/system-packages.test.ts

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}