---
name: rmm-spawn-headless-claude
description: Spawn a headless `claude -p` on any RMM-managed Windows box that has Claude Code installed — reaches isolated sites (AD2) the coord API can't
metadata:
  type: reference
---

Any RMM-managed Windows endpoint with Claude Code installed can run an autonomous headless
Claude, dispatched via a GuruRMM command — even a site that's isolated from the ACG coord API.
The RMM agent phones home outbound, so this works where [[ad2-comms-via-sync-only]] says coord
can't reach (coord `:8001` blocked ≠ RMM `:3001` blocked). Validated 2026-07-01 on AD2
(Dataforth DC, agent `cfa93bb6-...`, claude v2.1.181 at `C:\Users\sysadmin\.local\bin\claude.exe`).

Recipe:
- Dispatch with **`"context":"user_session"`** — needs an interactive logged-on user (check
  `quser`); an admin session comes back elevated. `claude` is a per-user install, not on the
  SYSTEM PATH, so SYSTEM context won't find it.
- **GOTCHA: unset `ANTHROPIC_API_KEY` first.** A stale machine-level `ANTHROPIC_API_KEY` (108-char)
  shadows the good OAuth creds and makes `claude -p` fail with `Invalid API key · Fix external API
  key`. `Remove-Item Env:\ANTHROPIC_API_KEY` (+ `$env:ANTHROPIC_API_KEY=$null`) before invoking →
  falls back to `~\.claude\.credentials.json` OAuth and authenticates.
- **Detach + poll.** A real audit run takes many minutes; RMM caps command lifetime (see
  [[gururmm-command-timeout-seconds]] — use `timeout_seconds`). Launch detached
  (`Start-Process powershell -File runner.ps1 -WindowStyle Hidden`), have the runner write the
  deliverable to a file + a `DONE.txt` marker, and poll the marker via short RMM commands.
- Run headless as: `claude -p <brief> --permission-mode bypassPermissions --output-format text`.
  For an audit, give an ironclad READ-ONLY brief (no writes/git/state changes) since
  bypassPermissions lets it run any tool. Pass the brief via a base64'd file to dodge quoting.
- Windows/Git-Bash: the mingw `curl` intermittently hits `Permission denied` (AV lock) —
  use `/c/Windows/System32/curl.exe` for the dispatch. See [[feedback_windows_quote_stripping]].

Use for: live audits/data-gathering on isolated or hard-to-reach managed boxes without the async
sync-handoff. Keep it read-only on production (AD2 is a domain controller).