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