lerkolabs/uptop repository overview

⁠uptop

Self-hosted uptime monitoring with a TUI over SSH.

No browser. No client install. Just ssh -p 23234 your-server.

⁠What is this

An uptime monitor you manage entirely from the terminal. It runs as a server, exposes an SSH endpoint, and drops you into a full TUI — monitors, alerts, logs, nodes, all there.

Built on RDGames/go-upkeep⁠. Rewritten for clustering, config-as-code, and a proper dashboard.

Canonical repo: gitea.lerkolabs.com/lerkolabs/uptop⁠ — GitHub⁠ is a mirror; releases are published to both.

⁠Features

• 6 check types — HTTP, Push (heartbeat), Ping, Port, DNS, Groups
• 10 alert providers — Discord, Slack, Email, Ntfy, Webhook, Telegram, PagerDuty, Pushover, Gotify, Opsgenie
• Config as code — define monitors in YAML, apply declaratively, version control your setup
• HA clustering — leader/follower with automatic failover
• Prometheus metrics — /metrics endpoint, wire it straight to Grafana
• Public status page — HTML + JSON, toggle with an env var
• SQLite or Postgres — SQLite for single-node, Postgres for production
• Uptime Kuma import — migrate from Kuma with one command

⁠Screenshots

⁠Quick start

UPTOP_ADMIN_KEY="$(cat ~/.ssh/id_ed25519.pub)" go run ./cmd/uptop
ssh -p 23234 localhost

Want some data to look at first:

UPTOP_ADMIN_KEY="$(cat ~/.ssh/id_ed25519.pub)" go run ./cmd/uptop -demo

⁠Install

services:
  uptop:
    image: lerkolabs/uptop:latest
    restart: unless-stopped
    ports:
      - "23234:23234"
      - "8080:8080"
    environment:
      - UPTOP_DB_TYPE=sqlite
      - UPTOP_DB_DSN=/data/uptop.db
      - UPTOP_STATUS_ENABLED=true
      # - UPTOP_ADMIN_KEY=ssh-ed25519 AAAA... you@host
    volumes:
      - ./data:/data
    sysctls:
      - net.ipv4.ping_group_range=0 2147483647

go install gitea.lerkolabs.com/lerkolabs/uptop/cmd/uptop@latest

Upgrading: Pull the new image (or binary) and restart. Database migrations run automatically on startup.

⁠Config as code

Export your current monitors:

uptop export -o monitors.yaml

Apply a config file:

uptop apply -f monitors.yaml
uptop apply -f monitors.yaml --dry-run   # see what would change
uptop apply -f monitors.yaml --prune     # delete anything not in the YAML

Full reference in docs/config-as-code.md⁠.

⁠Environment variables

See .env.example⁠ for all options including TLS, probes, and advanced settings.

⁠Running behind a reverse proxy

By default uptop ignores the X-Forwarded-For header and rate-limits by the direct connection address — so a client can't spoof the header to bypass limits. If uptop sits behind a reverse proxy (nginx, Caddy, Cloudflare, an ALB), set UPTOP_TRUSTED_PROXIES to the proxy's address(es) so the real client IP is used instead:

# single nginx/Caddy on the same host
UPTOP_TRUSTED_PROXIES=127.0.0.1

# a proxy subnet, or Cloudflare ranges
UPTOP_TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12

Only requests whose immediate peer is in this list have their X-Forwarded-For honored (right-most non-trusted hop wins). Bare IPs are treated as single hosts; invalid entries are warned about and skipped. Leave it unset if uptop is exposed directly.

⁠Encryption

Set UPTOP_ENCRYPTION_KEY to encrypt alert credentials (SMTP passwords, webhook URLs, API tokens) at rest with AES-256-GCM. Generate a key:

openssl rand -hex 32

Without this, credentials are stored as plaintext in the database. uptop warns on startup if unset. To encrypt credentials on an existing install, run uptop migrate-secrets with the key set.

⁠Data retention

uptop prunes its own history in the background — no external cleanup jobs needed:

Sparklines, uptime percentages, and SLA reports are computed from these windows, so very long-horizon stats aren't retained. Export to Prometheus via /metrics if you need unlimited history.

⁠Clustering

uptop supports three modes: leader (default single node), follower (HA failover — takes over if the leader goes down), and probe (stateless distributed checks from multiple regions).

See docs/clustering.md⁠ for setup guides, or the working examples in deploy/⁠.

⁠Migrating from Uptime Kuma

Export your Kuma backup JSON, then:

curl -X POST http://localhost:8080/api/import/kuma \
  -H "X-Uptop-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d @kuma-backup.json

⁠License

MIT — see LICENSE⁠.