---
name: hd-api-mac
description: >
  macOS platform companion to hd-api — the Apple/Lima-specific half of reaching HD's
  control API. The full endpoint catalog lives in hd-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, HD binding 0.0.0.0, and the
  nspawn machine-runtime endpoints (the /workspace/* routes, /wsl/* names kept for
  wire-compat). Mirror of hd-api-windows (the /wsl/* WSL networking tables). Trigger
  words — hd control api macos, adom-host, hd-control-url, reach HD from the workspace,
  machine runtime endpoints, vz loopback, workspace health macos.
---

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

This is the **macOS half** of `hd-api`. The endpoint catalog, `_manifest`, auth, and
every route table live in the generic **hd-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**, HD'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 HD. HD 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** HD 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 — that's the #1
macOS-specific failure when porting a Windows playbook that used a `\\wsl$`/loopback
path.

## Machine-runtime endpoints

The default macOS runtime is the **nspawn machine** (not Docker). HD exposes the
workspace-runtime routes under `/workspace/*` — and **keeps the `/wsl/*` route names as
wire-compat aliases**, so a caller written against the Windows tables 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 — the macOS analog of the Windows
UAC/installer dialogs.

## NOT here (lives in the Windows companion)

The `\\wsl$` share paths, WSL2 port-proxy / `netsh` forwarding, and the Windows
loopback-mirroring assumptions are in `hd-api-windows`. On macOS reachability is the
`adom-host` gateway + `~/.adom/hd-control-url`, full stop.