Agents

What the agent does

The agent is a lightweight binary you install on servers inside your network. It reports host metrics (CPU, memory, disk, network) and runs checks against targets unreachable from the public internet — databases, internal APIs, message queues, containers and private services. Agent targets are validated and dialed against pinned IPs, so internal monitoring cannot be turned into an SSRF or DNS-rebinding attack.

Installing

1. Create an agent in the dashboard (Uptime → Agents → New Agent) or via the API — you get an install token back
2. Run the install script on the target server — it registers, authenticates and starts reporting
3. The agent appears in your dashboard within seconds

# 1. Create the agent
curl -X POST https://api.shxrk.systems/api/v1/uptime/agents \
  -H "Authorization: Bearer sk_shx_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "db-primary", "hostname": "db-01.internal", "status_page_id": "<uuid>" }'

# 2. Install on the server (token from step 1)
curl -sSL "https://api.shxrk.systems/api/v1/uptime/agents/install?token=<agent_token>" | bash

The agent self-updates: it periodically checks GET /api/v1/uptime/agents/version for a new release. Update manifests are Ed25519-signed and every binary is checksum-verified before it replaces the running one — the agent rolls back automatically if a new version fails to start.

Security events

The agent can watch the host for security-relevant events and stream them into a per-agent event feed in the dashboard:

• Failed SSH login attempts
• Failed sudo invocations
• Pending package updates

Toggle each detector under Agents → Security. Events can be acknowledged, resolved and reopened — useful as a lightweight security pulse next to uptime data.

Service discovery

The agent can report services it finds listening on the host (port, protocol, process) as discovery suggestions. From the dashboard you review a suggestion and adopt it into a real monitor with one click — adoption enforces your plan's monitor limits and validates the reported host and port before anything is created.

Agent monitors

Monitors of type agent — and all infrastructure types like docker, kubernetes, proxmox, rabbitmq, kafka, mqtt and snmp — execute on the agent itself, so target can be an internal address like http://10.0.0.5:8080/health or rabbitmq.internal:15672 that our public checkers cannot reach:

curl -X POST https://api.shxrk.systems/api/v1/uptime/monitors \
  -H "Authorization: Bearer sk_shx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal API health",
    "type": "agent",
    "target": "http://10.0.0.5:8080/health",
    "agent_id": "<agent_uuid>",
    "status_page_id": "<status_page_uuid>",
    "interval": 60
  }'

API surface

The agent's own API

The agent binary authenticates with its own credentials — no user token on the server:

All agent endpoints are rate-limited per token rather than per IP, so fleets behind a shared NAT never starve each other.