---
name: hd-api-key-mac
description: >
  Diagnose and repair the workspace's Adom API key (`/var/run/adom/api-key`) on macOS
  Hydrogen Desktop — the injected session token that adom-cli and every Adom tool
  authenticate with. Use when adom-cli returns 401/unauthorized, `/var/run/adom/api-key`
  is missing or empty, "adom-cli can't reach Adom", or the user asks to reauthorize
  Adom / re-pull the API key. Covers: pulling the current token from HD via
  `GET /auth-token`, re-writing the key (passwordless sudo), prompting the user to
  sign in to HD when the host has no valid session, and triggering HD's
  inject-api-key setup step. Trigger words — api key, api-key, /var/run/adom,
  401 unauthorized, adom-cli auth, reauthorize adom, re-auth adom, pull api key,
  session token missing, fix adom auth, carbon 401.
---

# hd-api-key-mac — recover the workspace Adom API key

`/var/run/adom/api-key` (mode 644) holds the user's Adom **session token**, injected
into the `Adom-Workspace` machine by HD. `adom-cli` and the other Adom CLIs read it to
authenticate against carbon (through HD's proxy over `adom-host`). When it's missing
or stale, every Adom platform call fails — usually surfacing as `401`/`unauthorized`
from `adom-cli`.

## Why it goes missing (know before fixing)

- `/var/run` is **tmpfs** — a machine or Lima-VM reboot silently wipes the key even
  though the user's session on the Mac is still valid.
- HD writes it at three moments: the `inject-api-key` setup step, **every Adom auth
  completion**, and **on every HD launch** (the last two are HD ≥ 0.1.148; older HDs
  only wrote it during setup — if the user signed in *after* setup ran, the key never
  landed. That gap is exactly what this skill recovers).
- The setup step self-skips with "sign in later" when the user wasn't signed in yet.

## Diagnose (two commands)

```bash
wc -c /var/run/adom/api-key 2>/dev/null   # missing/0 bytes → key absent
timeout 15 adom-cli carbon user get        # 401/unauthorized → key stale or absent
```

| Symptom | Meaning | Fix |
|---|---|---|
| file missing/empty, host signed in | tmpfs wipe or pre-0.1.148 auth gap | Pull the token (below) |
| file present, `401` | host session rotated/expired since injection | Pull the token (below) |
| pull says no session on host | user isn't signed in to HD | Prompt reauthorization (below) |

## Fix — pull the current token from HD

HD's control API serves the raw session token at `GET /auth-token` (raw text when
signed in; a JSON `{"error":"no session token"}` object when not). The `adom` user
has passwordless sudo:

```bash
CTRL="$(cat ~/.adom/hd-control-url)"          # e.g. http://adom-host:<control> — see hd-api-mac
TOKEN="$(curl -sf "$CTRL/auth-token")"
case "$TOKEN" in
  ""|\{*) echo "NO SESSION on host — user must sign in to HD (see below)" ;;
  *) sudo mkdir -p /var/run/adom \
       && printf %s "$TOKEN" | sudo tee /var/run/adom/api-key >/dev/null \
       && sudo chmod 644 /var/run/adom/api-key \
       && echo "key written ($(wc -c < /var/run/adom/api-key) bytes)" ;;
esac
timeout 15 adom-cli carbon user get            # VERIFY — must return user JSON, not 401
```

Always verify with `adom-cli carbon user get` — a written key proves nothing if the
host session itself expired (then the pull "succeeds" but carbon still 401s →
reauthorization needed).

## Prompt the user to reauthorize

When the host has no session (or the pulled token still 401s), the fix is a human
step — **tell the user in chat**, plainly:

> Your Adom session has expired (or you're not signed in). Please bring up the
> Hydrogen Desktop window and sign in to Adom — I'll pick it up automatically and
> finish fixing the workspace auth.

Optionally also raise a native toast so they see it outside the editor (see
`hd-notifications-mac`). Then poll — on HD ≥ 0.1.148 auth completion re-injects the
key automatically:

```bash
for i in $(seq 1 60); do [ -s /var/run/adom/api-key ] && break; sleep 5; done
timeout 15 adom-cli carbon user get
```

If the key never appears (older HD), re-run the pull block above once the user
confirms they signed in.

## Alternative: trigger HD's setup step

`POST "$CTRL/setup/step/inject-api-key"` re-runs the injection through HD's Setup
panel (the panel is force-shown; the user sees live progress; the step also
validates against carbon). Use this when you want the user-visible, HD-audited path
instead of writing the file yourself. Do **NOT** use `POST /setup/run-step` — that
endpoint is deprecated and hard-refused.

## Related

- `hd-api-mac` — `~/.adom/hd-control-url` discovery + the `adom-host` gateway (why
  `127.0.0.1` doesn't reach HD from the machine).
- `hd-setup-steps` — where `inject-api-key` sits in the install cascade.