claudetools/.claude/memory/reference_gururmm_api.md

name, description, type

name	description	type
GuruRMM API — run PowerShell on any agent	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.	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

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)

{
  "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.