Skip to content
numbrs docs

Self-Hosting

Running your own instance of numbrs gives you full control over your data. The stack is a Vite/React frontend on Vercel and a Supabase database. The free tiers of both services are sufficient.

Estimated setup time: 15–20 minutes.

Prerequisites

Section titled “Prerequisites”

Step 1: Fork the repo

Section titled “Step 1: Fork the repo”

Go to github.com/satsdisco/numbrs and click Fork. This creates a copy in your GitHub account that you’ll deploy.

Step 2: Create a Supabase project

Section titled “Step 2: Create a Supabase project”
  1. Log into supabase.com and click New project
  2. Choose your organization, give the project a name (e.g. numbrs), and set a database password
  3. Pick a region close to you
  4. Click Create new project — it takes about 60 seconds to provision

Once the project is ready:

  1. Go to Project Settings → API
  2. Copy the Project URL — looks like https://abcdefgh.supabase.co
  3. Copy the anon public key — a long JWT string

Keep these handy; you’ll need them in the next step.

Step 3: Deploy to Vercel

Section titled “Step 3: Deploy to Vercel”

Click the button to deploy directly from your fork:

Deploy with Vercel

Or do it manually:

  1. Go to vercel.com/new
  2. Click Import Git Repository and connect your GitHub account
  3. Select your forked numbrs repo
  4. Vercel will detect the framework automatically (Vite)
  5. Before clicking Deploy, scroll to Environment Variables and add:
VariableValue
VITE_SUPABASE_URLYour Supabase project URL
VITE_SUPABASE_ANON_KEYYour Supabase anon/public key
  1. Click Deploy

The build takes about a minute. Once it’s done, you’ll get a .vercel.app URL.

Step 4: Run database migrations

Section titled “Step 4: Run database migrations”

The database tables don’t exist yet. You need to run the migration files from the repo.

  1. In your forked repo, find the migration files in supabase/migrations/ — they’re numbered in order
  2. In your Supabase project, go to SQL Editor
  3. Open each migration file and paste the contents into the SQL editor, then click Run
  4. Run them in order (lowest number first)

This creates all the tables, indexes, and row-level security policies that numbrs needs.

Step 5: Enable email auth

Section titled “Step 5: Enable email auth”

By default, Supabase projects have email authentication disabled. Turn it on:

  1. Go to Authentication → Providers in your Supabase project
  2. Find Email and toggle it on
  3. Under Auth Settings, decide whether to require email confirmation — for personal use, you can disable it so login is immediate

Step 6: Create your account

Section titled “Step 6: Create your account”

Go to your deployed Vercel URL and click Sign up. Create your account with the email and password you want to use.

That’s it — you’re in.

Keeping up to date

Section titled “Keeping up to date”

When the upstream repo (satsdisco/numbrs) gets updates:

  1. Sync your fork on GitHub (Sync fork button)
  2. Vercel will auto-deploy the updated code
  3. Check if there are new migration files in supabase/migrations/ and run them in the SQL editor

Troubleshooting

Section titled “Troubleshooting”

Blank page after deploying

Almost always missing environment variables. Double-check that VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are set in Vercel → Project Settings → Environment Variables. After adding them, trigger a redeployment (Deployments → click the three dots → Redeploy).

Can’t log in / “Email provider not enabled”

Go to Supabase → Authentication → Providers and enable the Email provider. Also check that your Supabase URL in the env vars doesn’t have a trailing slash.

“Invalid API key” error

Make sure you’re using the anon public key as VITE_SUPABASE_ANON_KEY, not the service role key. They look similar but serve different purposes.

Data not showing after running collector scripts

Check that all migration files ran successfully. If a table doesn’t exist, the collector will silently fail. You can verify by going to Supabase → Table Editor — you should see tables like claude_usage, openclaw_usage, uptime_checks, etc.

If tables exist but data isn’t showing, check that the RLS policies were applied. Go to Supabase → Authentication → Policies and confirm each table has policies defined.

Section titled “Related”