Self-hosting clrd

clrd is one binary with one SQLite file. Run it anywhere that can keep a port open, put HTTPS in front of it, and point your phones and scripts at it.

Run it

With Docker Compose (the docker-compose.yml in the repo root):

git clone https://github.com/thejdubb02/clrd && cd clrd
# set CLRD_BASE_URL in docker-compose.yml to your public https URL
docker compose up -d
docker compose logs clrd    # shows the one-time setup link

Or plain Docker:

docker build -t clrd .
docker run -d --name clrd -p 127.0.0.1:8080:8080 -v clrd-data:/data \
  -e CLRD_BASE_URL=https://clrd.example.com clrd

Both publish the port on localhost only (Docker 28 or newer keeps that from other machines on the same network), so tokens reach clrd through your HTTPS proxy and never cross the network in plain HTTP. If the proxy runs on another machine, publish the port on a private interface instead.

Or the binary (Go 1.23+, no C compiler needed):

CGO_ENABLED=0 go build -o clrd ./server/cmd/clrd
CLRD_DB=./clrd.db ./clrd serve

First run

With no admin token in the database, clrd logs a one-time link:

level=INFO msg="no admin token yet: open this link once to create one (or run `clrd token create`)" url=https://clrd.example.com/setup?code=...

Open it, name the device, and keep the token it shows: it is shown once. The link stops working as soon as any admin token exists. Anyone who can read the server log before you finish setup can use that link, so finish setup right after the first start.

On a headless box you can skip the link and make the token from the CLI instead (same database, so run it where the server runs):

docker compose exec clrd clrd token create --name me --scope admin

Tokens

Every phone, browser and script gets its own token, so a lost phone is one revoke and every dismissal shows which device did it.

clrd token create --name pixel-9 --scope read,publish
clrd token create --name backup-job --scope publish --topics backups
clrd token list

Scopes: read (see and act on notifications), publish (send), admin (manage tokens). --topics limits a token to those topics. Revoke with DELETE /api/v1/tokens/{id} (ids are in GET /api/v1/tokens); open streams for that token close at once.

Settings

Variable Default Meaning
CLRD_LISTEN :8080 Address to listen on.
CLRD_DB /data/clrd.db SQLite file. Its folder must be writable (WAL files live next to it).
CLRD_BASE_URL http://localhost:<port> Public URL, used in the setup link. Set it to your https URL.
CLRD_RETENTION 720h How long dismissed and resolved rows, and the event log, are kept.

HTTPS and the reverse proxy

Phones need HTTPS. The proxy must pass WebSocket upgrades and must not buffer streams. clrd sends a keepalive every 30 seconds, so idle timeouts of a minute or more are fine.

Caddy (handles certificates and WebSockets on its own):

clrd.example.com {
	reverse_proxy localhost:8080
}

nginx (the map goes in the http block):

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    proxy_read_timeout 1h;
}

Health

GET /healthz returns {"ok":true,"seq":N}. The Docker image runs clrd health as its health check. Point your uptime monitor at /healthz.

Backups

All state is the SQLite file. Stop clrd, copy clrd.db together with any clrd.db-wal and clrd.db-shm next to it, start clrd. Or, with the sqlite3 tool on the host, take a live copy:

sqlite3 /path/to/clrd.db ".backup /path/to/clrd-backup.db"

Phones keep their last sequence number. If you restore an older backup, they notice the server is behind them, drop their local copy and resync.

Coming from ntfy

clrd speaks ntfy's publish and subscribe API, so existing scripts, the ntfy CLI and webhook senders keep working. Change the server URL and use a clrd token:

curl -u :$CLRD_TOKEN -H "Title: Backup failed" -d "nas-1: exit 2" https://clrd.example.com/backups
ntfy publish --token $CLRD_TOKEN https://clrd.example.com/backups "nas-1: exit 2"
ntfy subscribe --token $CLRD_TOKEN https://clrd.example.com/backups

Send X-Id: <key> (or publish to /{topic}/{key}) to update one notification instead of stacking new ones, and Status: resolved with the same key to clear it everywhere when the problem goes away. Alertmanager and Grafana can post straight to https://clrd.example.com/<topic>?template=alertmanager: firing alerts appear, resolved alerts clear.

Not supported yet: attachments, icons, email and phone call forwarding, anonymous topics, Cache: no (refused, since clrd stores every notification to sync it), and http/broadcast action buttons (view actions work).

Upgrading

Pull, rebuild, restart. Take a backup first.

The full API is at /openapi.json on your server.