---
name: hd-setup-steps
description: What HD's setup steps did to prepare your workspace — the 18-step install sequence that imports the Adom-Workspace golden image, injects your Adom session, wires up the relay, and walks the Claude auth gate. Use this skill when the user asks "what did setup do", "why is X installed", "re-run a setup step", "what's a virgin reset", or "why did step N fail". Trigger words — setup steps, install steps, setup panel, virgin reset, re-run step, Run All, what did setup do, why is X installed, setup failed, install-tools, hd setup, claude code extension install, hd workspace ready.
---

# HD Setup Steps — what was done to prepare your workspace

Machine-runtime version (default). The legacy 24-step Docker cascade
(`HD_RUNTIME=docker`) is in the docker/ bucket.

When you first launched Hydrogen Desktop (or after a virgin reset), HD ran a 18-step install sequence to turn a blank workspace into a fully-tooled Adom workspace — the `Adom-Workspace` machine. The heavy tooling (code-server, the 8 Adom CLIs, the claude CLI + Code extension, VS Code settings, and all `hd-*` skills) is already BAKED into the golden image; setup just imports that image, injects your Adom session, wires up the relay, and walks the Claude auth gate. This skill explains what each step did so you can help the user understand their environment, re-run failed steps, or wipe and rebuild. See `hd-golden-image` for the baked-image model.

The cascade is executed by `setup_steps_macos.rs` (`step_defs_machine()` / `run_all_machine()`). `run_all_machine` is halt-on-failure, resume-not-restart, with per-step 3× auto-retry. In-machine work runs via `limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- bash -lc '<cmd>'` (the machine's DEFAULT user is `adom`, UID 1001, home `/home/adom`; under systemd-nspawn there's no wsl.conf — the default user comes from the machine config / nsenter `-S 1001 -G 1001`; root variant drops `-S 1001 -G 1001`). There is NO `docker exec` and NO Docker image anywhere in this flow.

## The 18 steps (in order)

| # | Step | Purpose |
|---|------|---------|
| 1 | ensure-workspace | Ensure the Lima VM `hd-builder` is up (provision it if missing — no host reboot needed on macOS), `machinectl import-tar Adom-Workspace` from the golden image `adom-golden.tar.gz` (full pre-baked image from the `adom-inc/hd-lima-image` GitHub release), create the `adom` user, start code-server, verify code-server reachable from the Mac on 7380. SUBSUMES the old Docker pull-image / create-container / start-container steps. |
| 2 | wait-codeserver | Host TCP probe of the code-server port (default 7380), 120s |
| 3 | install-adom-vscode | "Activate editor extensions" — installs NOTHING (binary + extension are baked); waits for Adom sign-in, reloads the editor iframe, and proves the :8821 editor-control API answers |
| 4 | set-env-vars | Set `ADOM_CARBON_URL`, `ADOM_HYDROGEN_URL`, `ADOM_HD_CONTROL_URL`, `VSCODE_PROXY_URI`, `ADOM_DESKTOP_MODE` |
| 5 | inject-api-key | Write the Adom session token into the machine at `/var/run/adom/api-key` (mode 644) so adom-cli works |
| 6 | configure-vscode | settings.json / trusted-domains / activity-bar are BAKED; re-asserts theme + workbench backstops idempotently, and applies the per-session layout via :8821 |
| 7 | ensure-adom-desktop | Verify the Adom Desktop companion app is running on the Mac (the relay's desktop bridge) |
| 8 | start-relay | Start the adom-desktop relay inside the workspace (ports 8765 WS / 8766 HTTP) |
| 9 | test-direct-connect | Prove the fast container→desktop command path |
| 10 | test-relay | Register the relay with Adom Desktop for file streaming (file transfer + shell exec) |
| 11 | test-adom-cli | GATE: carbon path + hydrogen-proxy reachability via adom-cli (6 retries) |
| 12 | claude-auth | The single human gate — restore Claude creds or drive the in-editor Claude.ai sign-in via the native browser Browser Picker; runs LAST before the payoff steps |
| 13 | ensure-sse | GATE: confirm the editor browser SSE session is connected so Welcome's webview-open doesn't 409 |
| 14 | verify-workspace | GATE: battery confirming the proxy holds a real layout |
| 15 | welcome | Open Claude Code, authenticate if needed, send the first prompt |
| 16 | open-welcome | GATE: open welcome.html in HD's right pane; hard-fails if the Welcome tab doesn't appear |
| 17 | eda-discovery | Opt-in payoff: opens a SECOND fresh Claude conversation and human-types a prompt to run `hd-eda-discovery` — quietly detects your EDA tools (KiCad, Fusion 360, Altium, OrCAD/Cadence) and reports what it found. Never blocks setup. |
| 18 | instapcb-quote | Opt-in payoff: opens a THIRD fresh Claude conversation and human-types a prompt to run `hd-instapcb` — finds your uploaded InstaPCB quotes + the quoting engine, then offers to wire the live KiCad→quote loop. Never blocks setup. |

### Steps that NO LONGER EXIST (baked into the golden image)

These are NOT setup steps anymore — they are baked at image-build time: `install-hd-skills`, `verify-adom-desktop`, `install-claude-cli`, `install-claude-ext`, `write-vscode-settings`, `set-trusted-domains`, `clean-layout`. If a user asks "what installed the Claude extension / my skills / VS Code settings", the answer is: **baked into the `adom-golden.tar.gz` golden image at build time, not a setup step.** See `hd-golden-image`.

## Common user questions

**"Why is X installed in my workspace?"** → If X is an Adom CLI, the claude CLI, the Claude Code extension, VS Code settings, or an `hd-*` skill, it was **baked into the golden image** — not run as a setup step. The setup steps only import the image, inject your session, wire the relay, and walk Claude auth. The setup panel (HD UI → bottom) lists every step with its current status.

**"Setup failed at step N"** → The setup panel shows the error. Most common failures: step 1 (Lima VM `hd-builder` not available / failed to provision, or the `adom-golden.tar.gz` download), step 11 (test-adom-cli — carbon/hydrogen-proxy not reachable yet), step 12 (Claude credentials expired). Each step has a retry button (and the cascade already retried it 3×).

**"Re-run a single step"** → In the setup panel, click the step row and use the Re-run action. Or via API: `POST http://127.0.0.1:47084/setup/step/<id>` (optional body `{"continue_after":true}` to keep going after it).

**"Re-run all steps"** → Click "Run All" in the setup panel; it resumes from the first not-done step. (The old headless `POST /setup/run-all` is now REFUSED.)

## Virgin reset

Virgin reset wipes parts of your workspace so setup can rebuild them cleanly. The ONLY programmatic trigger is `POST /setup/panel/run-virgin-reset`. Toggle which artifacts to delete (option keys in parentheses):

| Toggle (key) | What gets wiped | When to use |
|--------|----------------|-------------|
| Install step state (`install_state`) | Marks all steps as pending (`setup-steps-macos.json`) so they re-run | Always (default on) |
| Workspace machine (`container`) | PRISTINE `machinectl remove Adom-Workspace` + reimport — deletes the machine AND everything in it, including `/home/adom/project` | Always (default on); your work in `/home/adom/project` is GONE |
| Machine tarball (`tarball`, legacy `image`) | Deletes the cached `adom-golden.tar.gz` (full-image re-download) | Rarely — only if the tarball is corrupted |
| Webview storage (`webview_storage`) | Queued wipe, flushed at next HD launch (restart_required) | Rarely |
| VS Code state (`vscode_state`) | Queued wipe, flushed at next HD launch (restart_required) | Rarely |
| Adom session token (`adom_token`) | Deletes `hydrogen-session.txt`; forces re-login | Rarely |
| Claude credentials (`claude_token`) | Deletes the host-side Claude creds backup; forces Claude re-auth | When Claude auth is stuck |

`confirmed_destructive` must be set. After toggling, hit "Wipe Selected", then "Run All" to rebuild. The machine reset backs up Claude creds first UNLESS `claude_token` is checked; the `webview_storage` / `vscode_state` wipes are queued and flushed at the next HD launch (restart_required), not immediate.

CRITICAL: the machine reset ONLY ever runs `machinectl remove Adom-Workspace` (+ reimport). It never runs a global teardown — stopping/deleting the `hd-builder` Lima VM itself or running global `machinectl` teardown (those would kill the user's other Lima VMs / `machinectl` machines, including Docker-for-Mac's own VM), and it performs NO Docker actions and NO reboot for the wipe.

## Setup panel APIs (useful for AI automation)

| Endpoint | What it does |
|----------|--------------|
| `GET /setup/state` | Current state — `never-run`, `in-progress`, `complete`, or `error` |
| `POST /setup/step/<id>` | Re-run a single named step (optional `{"continue_after":true}`) |
| `POST /setup/panel/run-virgin-reset` | Trigger virgin reset with the supplied toggle options |
| `POST /setup/panel/show` | Open the setup panel from anywhere |

All on HD's control API at `http://127.0.0.1:47084`.

**DEPRECATED — now REFUSED, do not use:** `POST /workspace/unregister`, `POST /setup/virgin-reset`, `POST /setup/run-all`, `POST /setup/run-step`. Use `POST /setup/panel/run-virgin-reset` and `POST /setup/step/<id>` instead.

## Setup state file

Setup writes its state to `~/Library/Application Support/hydrogen-desktop/setup-steps-macos.json` (one entry per step with `status: pending|running|done|failed`, output text, percent complete). HD reads this on launch to decide whether the setup panel auto-opens. (The legacy Docker runtime uses `setup-steps.json`.)

## Related skills

- `hd-golden-image` — the baked-image model: what's pre-installed in `adom-golden.tar.gz` vs. what setup does
- `hd-container` — the workspace machine and runtime that setup configures
- `hd-networking` — how the machine reaches the host (via the `adom-host` gateway alias; live control URL in `~/.adom/hd-control-url`) and how ports forward
- `hd-browser-picker` — used by step 12 (claude-auth) for the Claude auth OAuth flow
- `hd-adom-auth` — how the Adom session token (step 5) gets injected
- `hd-volume` — where your files live in the machine and what survives a virgin reset (or doesn't)