93 lines
4.2 KiB
Markdown
93 lines
4.2 KiB
Markdown
---
|
|
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.
|