Private-network monitoring

thump's cloud probes run on Cloudflare's edge — they can reach anything public, and nothing behind your VPN, VPC, or office firewall. The thump agent closes that gap without opening a single inbound port.

How it works

The agent is a subcommand of the CLI that runs inside your private network:

On a fixed cadence it performs local HTTP checks against your internal endpoints.
Every check that passes pings a thump heartbeat (outbound HTTPS only).
A check that fails deliberately withholds its ping. The heartbeat goes late, and thump opens an incident through the exact same pipeline as any other monitor — alert channels, reminders, escalation, status pages, everything.

Dead-man's-switch semantics mean the failure modes compose correctly: an endpoint going down, the agent crashing, the host losing power, or the network dropping all look the same from outside — the pings stop, and you get paged. There is no state to reconcile and no API for the agent to poll.

Setup

In the dashboard, create one heartbeat per internal endpoint you want covered (Heartbeats → New). Set the expected interval to your agent cadence (60s cadence → 1 minute interval works well with the default tolerance). Copy each heartbeat's ping URL.
Write an agent config file, one check per endpoint:

{
  "intervalSeconds": 60,
  "checks": [
    {
      "name": "intranet wiki",
      "url": "http://wiki.internal:8080/health",
      "expectStatus": 200,
      "heartbeatUrl": "https://thump.dev/ingest/heartbeats/<token>"
    },
    {
      "name": "warehouse db admin",
      "url": "https://pgadmin.corp.local/login",
      "bodyContains": "Sign in",
      "timeoutMs": 5000,
      "heartbeatUrl": "https://thump.dev/ingest/heartbeats/<token2>",
      "heartbeatSecret": "<signing secret, if set on the heartbeat>"
    }
  ]
}

Run it:

thump agent --config ./thump-agent.json

--once runs a single round and exits (0 = all passed, 2 = something failed) — useful for cron-style scheduling or a smoke test.

Check options

Field	Default	Meaning
`url`	required	Internal endpoint to check (http/https)
`heartbeatUrl`	required	The thump heartbeat ping URL to report to
`name`	URL host	Label in agent logs
`method`	`GET`	HTTP method
`timeoutMs`	`10000`	Per-check timeout (100–120000)
`expectStatus`	any < 400	Exact status code required
`bodyContains`	—	Substring the response body must contain
`heartbeatSecret`	—	Signs pings with GitHub-format `X-Hub-Signature-256`
`intervalSeconds`	`60` (top level)	Cadence for all checks; minimum 10

Signed pings

If a heartbeat has a signing secret configured, set the same value as heartbeatSecret in the check. The agent signs the exact ping body with HMAC-SHA256 (X-Hub-Signature-256: sha256=<hex>) — unsigned or tampered pings are rejected, so a leaked ping URL alone can't fake liveness.

Running it for real

Anything that keeps a process alive works. A systemd unit is the usual answer:

[Unit]
Description=thump private-network agent
After=network-online.target

[Service]
ExecStart=/usr/local/bin/thump agent --config /etc/thump/agent.json
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Run one agent per network segment. Agents are stateless — replacing the host is just starting the binary somewhere else with the same config.