---
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
```bash
adom-desktop shell_execute '{"command":"ls ~/adom"}'
```

### Run something in the HD local workspace machine
```bash
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
```bash
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
```bash
adom-desktop desktop_screenshot_window '{"hwnd":HWND}'
```

### Pull file from the Mac to cloud
```bash
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.

## Related skills

- `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