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

# Hydrogen Desktop (macOS) — operate

The native macOS build of Hydrogen Desktop. Apple Silicon (arm64) only, macOS 13+.
First launch runs the whole setup automatically — no Homebrew, no Docker, no clicks.
The app downloads its own lightweight VM runtime (Lima) + the workspace image on first
run (both cached), so there are no manual prerequisites.

## Install

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

Or open the DMG and drag **Hydrogen Desktop** to **Applications**.

## First launch (near-hands-free setup)

Launching the app from /Applications runs the setup cascade. The only prompts are a
one-time Rosetta install and the Adom + Claude sign-in:

1. Installs **Rosetta** if missing (one click) — runs the x86-64 Adom tools in the workspace.
2. Brings up the bundled Lima utility VM `hd-builder` (Apple Virtualization.framework).
3. Imports the workspace machine `Adom-Workspace` from the bundled golden image, boots it.
4. Starts the editor (code-server), signs in to Adom + Claude, and connects the AI workspace.

## Troubleshooting

- **Gatekeeper warns on first open** ("developer cannot be verified") — this build is
  signed (Developer ID) but not yet notarized. Right-click the app → **Open** once to
  approve it, or install via `adom-wiki pkg install` which drops the quarantine flag.
- **"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`).
- **Reset the VM** (re-provision from scratch): `limactl delete hd-builder`, then
  relaunch the app.

## Uninstall

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