---
name: hydrogen-api-mac
description: >
  macOS platform companion to hydrogen-api — the Apple/Lima-specific half of reaching Hydrogen's
  control API. The full endpoint catalog lives in hydrogen-api (adom/hd-bootstrap); THIS
  skill carries only what differs on macOS: the adom-host gateway (vz doesn't mirror
  loopback), the ~/.adom/hd-control-url discovery file, Hydrogen binding 0.0.0.0, and the
  nspawn machine-runtime endpoints (the /workspace/* routes, legacy /wsl/* route names
  kept for wire-compat). Trigger
  words — hydrogen control api macos, adom-host, hd-control-url, reach Hydrogen from the workspace,
  machine runtime endpoints, vz loopback, workspace health macos.
---

# hydrogen-api (macOS) — reaching the control API across the Lima boundary

This is the **macOS half** of `hydrogen-api`. The endpoint catalog, `_manifest`, auth, and
every route table live in the generic **hydrogen-api** skill — read that first. This skill
only covers how the **Lima/nspawn boundary** changes *reachability* and *discovery* on
a Mac.

## Base URL + the adom-host gateway

- On the **macOS host**, Hydrogen's control API is `http://127.0.0.1:<dynamic>`.
- From **inside the workspace machine**, the Apple `vz` VM does **NOT** mirror host
  loopback, so `127.0.0.1` won't reach Hydrogen. Hydrogen binds its host services to `0.0.0.0` and
  the workspace reaches them through the **`adom-host` gateway**:
  `http://adom-host:<dynamic>`.

## ⭐ Finding the control port — `~/.adom/hd-control-url`

The port is dynamic. **From the workspace, read the discovery file** Hydrogen writes every
launch (already pointed at the `adom-host` gateway):

```bash
CTRL="$(cat ~/.adom/hd-control-url)"     # e.g. http://adom-host:<control>
curl -sf "$CTRL/health"
```

Never hard-code the port or assume `127.0.0.1` from inside the machine — the `vz` VM
does not mirror host loopback, so a loopback-based playbook fails here. The discovery
file is the only supported path.

## Machine-runtime endpoints

The default macOS runtime is the **nspawn machine** (not Docker). Hydrogen exposes the
workspace-runtime routes under `/workspace/*` — and **keeps the legacy `/wsl/*` route
names as wire-compat aliases**, so a caller written against the older route names still
resolves:

| Method | Path | Notes |
|---|---|---|
| GET | `/workspace/status` | machine registered / running / code-server reachable |
| GET | `/workspace/health` | deep health: machine + code-server + host reachability |
| GET | `/container-status` | runtime available, image/machine present, workspace running |

`/test/probe-dialogs` classifies **macOS permission prompts** (Screen Recording /
Accessibility / installer pkg) as blockers.

On macOS reachability is the `adom-host` gateway + `~/.adom/hd-control-url`, full stop.