Integrations Overview

numbrs integrations fall into two categories: native integrations that work automatically, and collector-based integrations that require a small script on your machine.

Native integrations

These are configured entirely in the numbrs UI. No local scripts, no cron jobs.

Integration	What it does
Relay monitoring	Checks Nostr relays every 5 minutes from numbrs’ servers
Uptime monitoring	Pings HTTP endpoints and records status and response time
Alerts	Fires notifications when thresholds are crossed or monitors go down

You add these from the sidebar. They start collecting data immediately.

Collector-based integrations

These require a small script that runs locally on your machine. The script reads data from local files or a local network service, then pushes it to your Supabase database via REST API.

Integration	Data source	Script location
Claude AI Usage	JSONL files on your Mac	Setup guide
Jellyfin	Jellyfin server API	Setup guide
Plex	Plex server API	Setup guide
Custom Metrics	Anything you script	API reference

How the collector pattern works

1. A bash/Python script runs on your machine (or wherever your data lives)
2. It reads local data — JSONL session files, a media server API, cron job output
3. It pushes records to your Supabase database using the REST API
4. It runs on a cron every 5 minutes (or whatever interval makes sense)
5. It’s idempotent — running it twice won’t create duplicates

The scripts only process data from the last 2 hours by default, so each run is fast. You can modify them to backfill historical data when you first set up.

All data written to Supabase is protected by row-level security — only your account can read your data.

Finding your credentials

All collector scripts need three environment variables:

NUMBRS_SUPABASE_URL — Your Supabase project URL.

• Managed (numbrs.lol): Go to Settings → API in the app
• Self-hosted: Your Supabase project URL from Project Settings → API

NUMBRS_SUPABASE_SERVICE_KEY — The Supabase service role key.

• Managed: Go to Settings → API in the app
• Self-hosted: Your Supabase project’s service role key from Project Settings → API → service_role

Caution

The service role key bypasses row-level security. Treat it like a database password. Don’t commit it to git or put it in code that gets shared. It should only ever live in environment variables on your local machine.

NUMBRS_OWNER_ID — Your user ID in numbrs.

• Go to Settings → Profile — your user ID is shown there as a UUID

Running your first collector

Once you have your credentials, the general pattern for any collector is:

# Set credentials
export NUMBRS_SUPABASE_URL="https://your-project.supabase.co"
export NUMBRS_SUPABASE_SERVICE_KEY="your-service-role-key"
export NUMBRS_OWNER_ID="your-user-id"

# Run the collector
bash ~/numbrs-collector.sh

Then set it up as a cron job:

*/5 * * * * NUMBRS_SUPABASE_URL=... NUMBRS_SUPABASE_SERVICE_KEY=... NUMBRS_OWNER_ID=... bash ~/numbrs-collector.sh >> /tmp/numbrs.log 2>&1

Related

• Claude AI Usage — track token counts and costs
• Custom Metrics — push anything via HTTP
• Jellyfin — media server stats
• Plex — media server stats