# Adom Hydrogen (macOS)

The full Adom Hydrogen workspace as a native **macOS** app — AI-driven electronics
design, running locally on Apple Silicon.

This is the macOS build of [Adom Hydrogen](/adom/hydrogen) (also available
for Windows). First launch runs the entire setup **hands-free** — no Homebrew, no
Docker, no manual prerequisites. The app provisions its own lightweight VM runtime
(Lima on Apple's Virtualization.framework), downloads the workspace image, and
converges the latest tooling and skills straight from this wiki. The only human
moments are a one-time **Rosetta** install (one click, if you don't already have it)
and your Adom + Claude sign-in — and if you've used Claude on this Mac before, even
the Claude sign-in restores automatically.

![The workspace running natively on macOS — VS Code + Claude on the left, an Adom webview on the right](screenshots/workspace-macos.png)

## Requirements

- **Apple Silicon** Mac (M1 or newer) — arm64 only.
- **macOS 13 (Ventura) or later** — uses Apple's Virtualization.framework.
- **Rosetta 2** — runs the x86-64 Adom tools inside the workspace. Hydrogen installs
  it for you on first launch if it's missing (one click); no Terminal needed.
- **Network on first launch** — downloads the VM runtime (~30 MB) + workspace image
  (~600 MB) once (cached after), then installs the current skills and editor tooling
  from the wiki.
- ~4 GB free disk for the workspace VM + image. The VM sizes itself to your machine
  (defaults: ¼ of RAM, 5% of disk) and is adjustable in **Settings → Workspace**.
- **Bare-metal Mac** — won't run inside a nested VM (Apple Silicon doesn't support
  nested virtualization).

## Install

Download the DMG from the **Releases** tab, open it, and drag **Adom Hydrogen** to
**Applications**. Releases are signed (Developer ID), notarized by Apple, and
stapled — Gatekeeper opens them without warnings.

Or install from the command line — Homebrew:

```bash
brew tap adom-inc/adom
brew install --cask adom-hydrogen
```

or the Adom Wiki CLI:

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

## What happens on first launch

The app runs the workspace setup automatically, streaming every step live:

1. Installs **Rosetta** if it's missing (one click).
2. Provisions the Lima utility VM (`hd-builder`) sized to your machine, downloads the
   golden workspace image, and boots the `Adom-Workspace` machine.
3. Installs the current Hydrogen skills, editor extensions, and settings fresh from
   the wiki (the image ships only the static OS/editor layer, so every install gets
   today's published tooling).
4. Starts the editor (code-server), signs you in to Adom + Claude — restoring saved
   Claude credentials automatically when possible — and opens your first AI
   conversation.

x86-64 Adom tools run under Rosetta inside the workspace; native arm64 code-server /
Node / Claude run directly.

## Day to day

- The menu-bar widget animates while AI prompts run and collects finished-chat
  notifications; click the Adom mark to open them (or the app).
- Quitting the app stops the workspace VM by default (change under **Settings →
  On Close** to keep it running in the background, or to be asked each time).
- Updates are checked automatically and staged in the background; the app tells you
  when a new version is ready.

## Uninstall

Open the DMG and double-click **Uninstall Adom Hydrogen** — it walks you through the
tiers (the app, the workspace VM with your project files, and the Adom Bridge
companion) and never touches other Lima VMs or anything you installed yourself.

Or from the command line:

```bash
adom-wiki pkg uninstall adom/hydrogen-macos
limactl delete hd-builder                                  # also remove the workspace VM
rm -rf "$HOME/Library/Application Support/adom-hydrogen" \
       "$HOME/Library/Application Support/adom"            # app state + cached image
```