sync: auto-sync from GURU-5070 at 2026-06-02 07:25:49

Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-06-02 07:25:49

.claude/memory/reference_gururmm_api.md

@@ -0,0 +1,92 @@
+---
+name: GuruRMM API — run PowerShell on any agent
+description: API endpoints, auth flow, and curl recipe to execute a script on any GuruRMM agent and retrieve output. Use this instead of asking user to paste script into ScreenConnect.
+type: reference
+---
+
+# GuruRMM API — Execute Script on an Agent
+
+**API base:** `http://172.16.3.30:3001` (reachable from HOWARD-HOME and similar dev machines via Tailscale — not reachable from cascades internal-network-only boxes, but that doesn't matter since the API talks to the agent, not the target machine).
+
+**Auth creds:** `infrastructure/gururmm-server.sops.yaml` → `credentials.gururmm-api.admin-email` + `admin-password`. Login returns a JWT valid for ~24h (expires 86400s from iat).
+
+## Flow
+
+```bash
+VAULT="$PWD/.claude/scripts/vault.sh"
+EMAIL=$(bash "$VAULT" get-field infrastructure/gururmm-server.sops.yaml credentials.gururmm-api.admin-email)
+PASS=$(bash  "$VAULT" get-field infrastructure/gururmm-server.sops.yaml credentials.gururmm-api.admin-password)
+
+JWT=$(curl -s -X POST http://172.16.3.30:3001/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASS\"}" \
+  | python -c "import json,sys; print(json.load(sys.stdin)['token'])")
+
+# List agents (find the agent_id for the host you want)
+curl -s http://172.16.3.30:3001/api/agents -H "Authorization: Bearer $JWT"
+
+# Submit a PowerShell command — works with any file, json-encode to preserve quotes/newlines
+AGENT="<agent-uuid>"
+PAYLOAD=$(python -c "
+import json
+with open('path/to/script.ps1','r',encoding='utf-8') as f: s=f.read()
+print(json.dumps({'command_type':'powershell','command':s}))
+")
+RESP=$(curl -s -X POST http://172.16.3.30:3001/api/agents/$AGENT/command \
+  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" -d "$PAYLOAD")
+CMD_ID=$(echo "$RESP" | python -c "import json,sys; print(json.load(sys.stdin)['command_id'])")
+
+# Poll until completed (status values: running, completed, failed, timeout)
+while true; do
+  STATUS=$(curl -s http://172.16.3.30:3001/api/commands/$CMD_ID -H "Authorization: Bearer $JWT" \
+    | python -c "import json,sys; print(json.load(sys.stdin)['status'])")
+  [ "$STATUS" != "running" ] && break
+  sleep 5
+done
+
+# Fetch result (stdout / stderr / exit_code)
+curl -s http://172.16.3.30:3001/api/commands/$CMD_ID -H "Authorization: Bearer $JWT"
+```
+
+## Required request fields
+
+`POST /api/agents/:id/command` requires:
+- `command_type` — the interpreter. Valid values include `powershell`, `shell`, `script`, `exec` — any string is accepted by the API but the Windows agent only runs powershell-compatible content. Use `powershell` for Windows agents.
+- `command` — the script text. JSON-encode to preserve newlines, quotes, and dollar-sign escapes.
+
+## Response shape (from `/api/commands/:cmd_id`)
+
+```json
+{
+  "id": "uuid",
+  "agent_id": "uuid",
+  "command_type": "powershell",
+  "command_text": "...",
+  "status": "completed",   // or running | failed | timeout
+  "exit_code": 0,
+  "stdout": "...",
+  "stderr": "...",
+  "created_at": "ISO-8601",
+  "started_at": "ISO-8601",
+  "completed_at": "ISO-8601"
+}
+```
+
+## When to use this
+
+- Readiness / diagnostic checks on any client server where GuruRMM is installed
+- One-off remediation without needing ScreenConnect copy-paste
+- Anywhere you'd otherwise ask the user to paste a script manually
+
+## When NOT to use this
+
+- When the agent isn't enrolled in GuruRMM (check `GET /api/agents` first)
+- For interactive sessions (no stdin; single-shot execution)
+- For >1 MB of script (untested — keep scripts modular)
+
+## Notes
+- Script output is limited; if you need large output, have the script write to a file on the agent and fetch via a separate command
+- `command_type: "powershell"` runs in the SYSTEM context on Windows (agent runs as LocalSystem)
+- Idempotent commands only — there is no transactional rollback
+- The tunnel API (`/api/v1/tunnel/...`) is a planned interactive feature per `.claude/gururmm-tunnel-plan.md`, not yet deployed as of 2026-04-22. Stick to `/api/agents/:id/command` for now.
+- Agents enrolled as of 2026-04-22 include CS-SERVER (`6766e973-e703-47c1-be56-76950290f87c`) for Cascades, DESKTOP-DLTAGOI for Cascades LE, AD2 for AZ Computer Guru. Use `GET /api/agents` for the live list.