upcheckr docs — quickstart, push API, self-host

Quickstart

1. Download & run the binary, open http://localhost:8080, set a password.

# macOS / Linux UPCHECKR_ADMIN_PASSWORD=secret ./upcheckr-macos-arm64

2. On the API keys screen, create a key. It's shown once — keys look like acme_prod_… (derived from your instance + source name).

3. Push a value from anywhere:

curl -X POST http://localhost:8080/api/v1/metrics \ -H "X-API-Key: acme_prod_…" \ -d '{"name":"active_users","value":52,"instance":"web-1"}'

The tile appears on the wall instantly and updates live as more values arrive.

The push API

POST /api/v1/metrics with header X-API-Key: <key>. The body is a batch of points (up to 1000). Content-Type is optional — a bare curl -d works.

{ "metrics": [ { "name": "active_users", "value": 52, "instance": "web-1", "type": "gauge", "labels": {"region":"eu"}, "ts": 1730000000000 } ] }

field	required	notes
name	yes	1–120 chars; letters, digits, spaces, `_ . : -`. Auto-registers on first push.
value	yes	finite number (NaN/±Inf rejected).
instance	no	which server/stream reported it; aggregations roll up across instances.
type	no	`gauge` \| `counter`, set on first push.
labels	no	JSON object of dimensions.
ts	no	epoch ms; defaults to server time.

Each request is validated synchronously and returns immediately — { "accepted": N, "rejected": [...] } — then persisted by a background writer (so your app is never blocked on the database). Invalid items are skipped; the good ones still land.

Node

await fetch("http://localhost:8080/api/v1/metrics", { method: "POST", headers: { "X-API-Key": "acme_prod_…", "Content-Type": "application/json" }, body: JSON.stringify({ metrics: [{ name: "active_users", value: 52, instance: "web-1" }] }), });

Python

import requests requests.post("http://localhost:8080/api/v1/metrics", headers={"X-API-Key": "acme_prod_…"}, json={"metrics": [{"name": "active_users", "value": 52, "instance": "web-1"}]})

Aggregations

Each tile rolls a metric up across the instances reporting in. Pick one per metric:

agg	what it shows
last	the single most-recent value
sum	total across instances
avg	average across instances
min / max	lowest / highest
count	number of samples in the window
rate	summed increments ÷ window seconds
p95	95th-percentile of the raw samples

Set a threshold per metric to color the bars (green → amber → red) and flag warning/over — free on every tier. The metric detail page adds Combined / Stacked / Overlaid per-instance views.

Self-host

One binary, no dependencies. Download for your platform (or use the JVM jar on Intel Macs).

env var	default	what
UPCHECKR_ADMIN_PASSWORD	generated	admin login password (printed once if unset).
UPCHECKR_DB	~/.upcheckr/upcheckr.db	SQLite file path.
UPCHECKR_INSTANCE_NAME	acme	shown in the UI; seeds the key prefix.
UPCHECKR_RETENTION_DAYS	7	rolling datapoint window.
UPCHECKR_HOST	—	public domain used in push examples.

Point a display at it and hit Wall mode for a chrome-free, fullscreen wall — perfect for a TV. Data persists in SQLite across restarts; back up or migrate via Settings → Export / Import.