---
name: hydrogen-macos
description: Operate Adom Hydrogen on macOS (Apple Silicon) — install from the DMG, run the hands-free first-launch setup, and troubleshoot the Lima workspace VM. Use when a user is installing or running the native macOS build of Adom Hydrogen, or the workspace machine won't come up. Trigger words — Adom Hydrogen mac, Hydrogen macOS, install Adom Hydrogen mac, lima workspace, hd-builder, Adom-Workspace, mac dmg hydrogen.
---

# Adom Hydrogen (macOS) — operate

The native macOS build of Adom Hydrogen. Apple Silicon (arm64) only, macOS 13+.
First launch runs the whole setup automatically — no Homebrew, no Docker, no manual
prerequisites. The app provisions its own Lima VM runtime, downloads the workspace
image (cached after), and installs the current skills + editor tooling fresh from the
wiki on every setup.

## Install

Download the DMG from the Releases tab and drag **Adom Hydrogen** to
**Applications** — releases are notarized and stapled, so Gatekeeper opens them
without warnings. Or:

```bash
adom-wiki pkg install adom/hydrogen-macos
```

## First launch (hands-free setup)

Launching the app runs the setup cascade, streaming each step live. The only prompts
are a one-time Rosetta install and the Adom + Claude sign-in (saved Claude
credentials restore automatically):

1. Installs **Rosetta** if missing (one click) — runs the x86-64 Adom tools in the workspace.
2. Provisions the Lima utility VM `hd-builder` (Apple Virtualization.framework),
   sized to the machine (¼ RAM / 5% disk defaults; adjustable in Settings).
3. Downloads the golden image, imports + boots the `Adom-Workspace` machine.
4. Installs the Hydrogen skills, editor extensions, and settings from the wiki.
5. Starts the editor (code-server), signs in to Adom + Claude, and opens the first
   AI conversation.

## Troubleshooting

- **"Rosetta is required" gate, or the workspace download hangs forever** — you're
  almost certainly running inside a **nested VM** (e.g. VirtualBuddy). Apple Silicon
  doesn't support nested virtualization, so the workspace VM can't boot. Run on a real
  Mac (a separate user account is a fine clean test environment).
- **Workspace won't start** — check the VM: `limactl list` should show `hd-builder`
  running. Inspect the machine: `limactl shell hd-builder -- sudo machinectl list`
  (expect `Adom-Workspace`).
- **Workspace stopped after quitting the app** — that's the default (On Close →
  "Stop workspace"). Change it in Settings to keep the VM running in the background.
- **Reset the VM** (re-provision from scratch): `limactl delete hd-builder`, then
  relaunch the app. Or use the app's own reset panel (Setup → Reset) for a guided
  virgin reset.

## Uninstall

Double-click **Uninstall Adom Hydrogen** on the DMG (guided tiers: app / workspace
VM / Adom Bridge companion), or:

```bash
adom-wiki pkg uninstall adom/hydrogen-macos
```