bootstrap

Hydrogen Desktop (macOS / Lima)

Public Made by Adom

by adom

The macOS platform layer for Hydrogen Desktop.

bootstraphydrogen-desktophdmacosmaclimanspawn
Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity
hd-mac-bootstrap / README.md
Download

adom/hd-mac-bootstrap

The macOS platform layer for Hydrogen Desktop. On a Mac, HD's workspace runs inside a Lima Ubuntu VM (hd-builder) that hosts the Adom-Workspace systemd-nspawn machine; this package adds everything specific to that runtime on top of the platform-generic adom/hd-bootstrap.

Hydrogen Desktop running natively on macOS — VS Code + Claude on the left, an Adom webview on the right, workspace in the local Lima/nspawn machine
adom-wiki pkg install adom/hd-mac-bootstrap --allow-sudo   # the golden Lima image bakes this;
                                                           # HD's setup re-converges it every install

The platform-layered bootstrap stack

adom/core                         ← Adom ecosystem (generic; shared with web Hydrogen)
  └─ adom/hd-bootstrap            ← Hydrogen Desktop, platform-GENERIC
       ├─ adom/hd-windows-bootstrap   ← WSL2 runtime
       ├─ adom/hd-mac-bootstrap       ← THIS — Lima/nspawn runtime
       └─ adom/hd-ubuntu-bootstrap    ← native-Ubuntu runtime

Each platform layer depends on adom/hd-bootstrap, which depends on adom/core, so core stays generic across web + desktop Hydrogen and every host OS.

What this layer adds

  • Dependencies: adom/hd-bootstrap (generic HD) + adom/adom-workspace-updater (the in-machine systemd updater daemon).
  • Bundled skills: the macOS-runtime hd-* skills — hd-container, hd-container-stats, hd-networking, hd-ports, hd-port-watcher, hd-setup, hd-setup-steps, hd-topology, hd-volume, hd-workspace-lifecycle, hd-workspace-monitoring (the Lima/nspawn analogs of the Windows layer's WSL2 set, sourced from hydrogen-desktop/skills/public-facing/machine/).
  • install script: deploys those skills into ~/.claude/skills/ on top of the generic layer, and installs the shot helper (~/.local/bin/shot) — one-call, token-efficient workspace screenshots that print only a PNG path (see hd-self-screenshot-mac) — plus the Adom-branded Claude Code statusline (~/.claude/statusline.sh: model + context bar + 5h usage; only set when the user hasn't configured their own). Note adom-wiki pkg install does not re-run install scripts for already-baked packages — HD's setup cascade (0.1.135+) runs the chain's deploy scripts explicitly (core → hd-bootstrap → hd-mac-bootstrap) so a fresh skills release actually reaches an already-baked machine.

The runtime difference vs. the Windows layer

The workspace is Linux in both cases — the layers differ only in where that Linux runs and how the host reaches it:

Windows layer macOS layer (this)
Linux host WSL2 Ubuntu distro Lima VM (hd-builder) → nspawn machine (Adom-Workspace)
Provisioning wsl --import of the golden WSL2 image machinectl import-tar of the golden Lima image
Host↔workspace \\wsl$ share + WSL networking Lima virtiofs share + adom-host gateway
Golden image hd-wsl2-image hd-lima-image

The mixed-skill split (<name>-mac companions)

adom/hd-bootstrap carries the 31 platform-generic hd-* skills. The Windows layer split 13 mixed skills into <name>-windows companions (e.g. hd-api-windows, hd-notifications-windows, hd-setup-windows) — the generic core stays in hd-bootstrap, the Windows half drops into hd-windows-bootstrap. This layer carries the parallel macOS halves in skills/<name>-mac/.

Companions authored (11):

  • hd-api-mac — adom-host gateway, ~/.adom/hd-control-url discovery, vz-no-loopback, /workspace/* (nspawn) endpoints (mirror of hd-api-windows' /wsl/* tables).
  • hd-api-key-mac — diagnose/repair the injected /var/run/adom/api-key session token (adom-cli 401s, tmpfs wipe on machine reboot, pre-0.1.148 post-auth gap): pull via GET /auth-token, prompt the user to reauthorize, or trigger the inject-api-key setup step.
  • hd-notifications-mac — Notification Center toasts + emergency Dock-bounce + the Notifications grant (mirror of hd-notifications-windows' WinRT/AUMID).
  • hd-recording-mac — the native recorder is #[cfg(windows)], so on macOS recording is in-app getDisplayMedia / pup / AD relay; ScreenCaptureKit native recorder not yet built (honest gap). Screen Recording TCC.
  • hd-screen-lock-mac — IOKit IOPMAssertionCreateWithName/PreventUserIdleDisplaySleep, pmset -g assertions, caffeinate (vs SetThreadExecutionState).
  • hd-self-screenshot-mac — screencapture/CoreGraphics + CDP Page.captureScreenshot; per-panel crop resolves the rect via the dom.measure RPC (no CDP on WKWebView) + image-crate crop (vs Win32 PrintWindow).
  • hd-browser-picker-mac — WKWebView-over-localhost interception + LaunchServices open -a native browsers (vs WebView2/COM 6-layer interception).
  • hd-permissions-mac — the macOS TCC model (Screen Recording, Accessibility, Automation, Camera/Mic) + preflight/relaunch (vs UAC).
  • hd-open-url-mac — open/open -a … --new-window LaunchServices launch + control-URL discovery (vs chrome.exe/msedge.exe).
  • hd-ui-mac — driving the UI via the hd-ui-command→/ui/_result command bus + invoke_ui_action (WKWebView has no CDP; raw CDP clicking is Windows-only).
  • hd-captions-mac — workspace caption is platform-neutral; the desktop overlay (desktop_caption) is a Windows-only stub on macOS (honest gap).

Reconcile the exact 13-skill set against adom/hd-windows-bootstrap's companions (its source is --hide-source sealed; read it from a workspace with org access). The machine-bucket skills above ship whole (they map to the Windows layer's clean skills, not its mixed companions).

Note: the macOS-runtime skills in skills/ that are whole (the machine/ bucket — hd-setup, hd-container, …) correspond to the Windows layer's clean skills, not its mixed companions, so they ship complete rather than as -mac halves. The exact 13-skill set should be reconciled against adom/hd-windows-bootstrap's companions (its source is --hide-source sealed; read it from a workspace with org access).

NOTE — naming: the canonical sibling slug is hd-mac-bootstrap (as referenced by adom/hd-windows-bootstrap's own description and stack diagram), not hd-macos-bootstrap.