upcheckr docs — quickstart, push API, aggregations, self-host

Quickstart

1. Download & run the binary — it asks you to set an admin password on first run — then open http://localhost:7090.

# macOS / Linux — first run prompts for a password chmod +x upcheckr-macos-arm64 ./upcheckr-macos-arm64 # add --port 9000 to change the port

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:7090/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:7090/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:7090/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	—	admin password. If unset, you're asked on first run (or one is generated & printed when there's no terminal, e.g. Docker).
UPCHECKR_PORT	7090	HTTP port (or pass `--port`).
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.

CLI flags: --port <n>, --reset-password (change the admin password without deleting the database), --version, --help.

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.

Security

upcheckr is built to sit safely on your own infrastructure. The dashboard and the ingest API authenticate separately, and the self-hosted binary makes no outbound calls — no telemetry, no phone-home, no license check.

Admin session — the dashboard sits behind an admin password, stored as a BCrypt hash at rest. Change it anytime with upcheckr --reset-password.
Login protection — sign-in is rate-limited: 10 failed attempts trigger a short lockout.
API keys — sources push with an X-API-Key that is shown once at creation and stored hashed. Revoking a key is immediate.
CSRF — every state-changing dashboard call is CSRF-protected.
Ingest limits — push bodies are capped at 5 MB and validated synchronously; invalid points are rejected item-by-item.
Verifiable downloads — every released file ships with a matching .sha256 checksum.

Run it on a private network or behind your usual reverse proxy for TLS; it's a single process with a single SQLite file, so the audit surface stays small.

Download the binary See the wall in action