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 / skills / hd-topology / SKILL.md
Download

name: hd-topology description: > MUST READ before ANY HD work. Explains the three-layer topology: cloud Docker (where Claude runs), the user's Mac (where HD + Adom Desktop run), and the HD local workspace (the Adom-Workspace machine). Every command you run goes through the relay to the Mac. You CANNOT directly access the workspace machine — you must shell through the Mac. Trigger words — HD topology, cloud vs local, machine exec, nsenter, where am I, which workspace, adom-desktop relay, test from container, three tiers, architecture, mac machine.

Hydrogen Desktop — Topology (READ FIRST)

Machine-runtime version (default). Legacy Docker container runtime (HD_RUNTIME=docker) is in the docker/ bucket.

You are NOT on the user's machine

You (Claude) run inside an Adom cloud Docker container. The user's Mac is a remote target you reach through the adom-desktop CLI relay. There are THREE separate environments:

1. Cloud Docker (where you run)

  • Your shell, your filesystem, your git repos
  • adom-desktop CLI connects to Adom Desktop on the Mac via relay
  • This container has NOTHING to do with HD's local workspace
  • Restarting the workspace machine on the Mac does NOT affect you
  • You can freely git push, edit code, run builds here

2. The user's Mac (user's desktop)

  • Adom Desktop — relay client app, listens on port 8770 (direct connect)
  • Hydrogen Desktop — the Tauri app you're building
  • Lima VM (hd-builder) — hosts the Adom-Workspace machine
  • You reach this via adom-desktop shell_execute '{"command":"..."}'
  • Commands run in a shell on the Mac (zsh/bash)

3. HD Local Workspace (machine) (the Adom-Workspace machine)

  • Machine name: Adom-Workspace (fixed — no random suffix, no container name)
  • Runs code-server, adom-desktop CLI, relay server
  • You reach this via: adom-desktop shell_execute '{"command":"limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- <cmd>"}'
  • This is TWO hops: cloud → relay → Mac → nsenter into the machine

Command Patterns

Run something on the Mac

adom-desktop shell_execute '{"command":"ls ~/adom"}'

Run something in the HD local workspace machine

adom-desktop shell_execute '{"command":"limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- ls /home/adom"}'

Test adom-desktop CLI inside the workspace machine

adom-desktop shell_execute '{"command":"limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- adom-desktop ping"}'

This tests the FULL chain: machine → local relay → Adom Desktop on the Mac.

Screenshot HD window

adom-desktop desktop_screenshot_window '{"hwnd":HWND}'

Pull file from the Mac to cloud

adom-desktop pull_file '{"filePaths":["/Users/.../file"],"saveTo":"/tmp"}'

The workspace machine ≠ Your Container

  • If the Adom-Workspace machine on the Mac goes down, YOUR cloud container is fine
  • You can still talk to Adom Desktop, screenshot windows, run shell commands
  • You just can't nsenter into the workspace machine until it's back
  • Starting/stopping the machine on the Mac is done via shell_execute. Only ever touch Adom-Workspace (machinectl terminate Adom-Workspace) — NEVER tear down the shared Lima VM hd-builder wholesale or run a global machinectl teardown, which would knock out any other Lima VM / machine the user has.

The Relay Chain

Cloud adom-desktop CLI
  → WS relay (cloud :8765)
    → internet
      → Adom Desktop on the Mac (relay client)
        → executes command locally
          → returns result
            → back through relay to your CLI

For the HD local workspace machine, there's a SECOND relay:

Workspace's adom-desktop CLI
  → local relay (machine :8765)
    → code-server proxy (:7380/proxy/8765/)
      → Adom Desktop on the Mac (connected as WS client)
        → executes command
          → returns through same chain

Critical Setup Steps for the HD Local Workspace (machine)

The HD install flow MUST verify this chain works:

  1. Verify Adom Desktop running on the Mac — probe port 8770 If not running: tell user to install from wiki and launch it
  2. Install adom-desktop CLI into the workspace — download binary
  3. Start relay inside the workspace — adom-desktop serve
  4. Register relay with Adom Desktop — server_add via direct connect URL: ws://127.0.0.1:{code_server}/proxy/8765/
  5. Test round-trip — limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- adom-desktop ping Must return pong — proves the full chain works

NEVER Do These

  1. NEVER confuse your cloud Docker with the HD local workspace machine. curl http://127.0.0.1:8766/health hits YOUR relay, not the workspace's.
  2. NEVER try to enter the machine from your cloud shell. The machine lives in the Lima VM on the Mac, not here.
  3. NEVER assume the workspace's status affects your container. They're completely independent.
  4. NEVER tear down the shared Lima VM hd-builder wholesale or run a global machinectl teardown of anything other than Adom-Workspace. Scope to the Adom-Workspace machine only (machinectl terminate Adom-Workspace) so the user's other Lima VMs / machines stay safe.
  5. NEVER skip the adom-desktop round-trip test. The relay chain has many links — test end-to-end, not individual parts.
  • hd-container — facts about the Adom-Workspace machine you run inside
  • hd-volume — where your files live and how to back up / copy out the machine