Skip to main content
HQ uses your own Supabase project as its database, auth system, real-time event stream, and storage backbone. You own this project — HQ never touches a shared backend.
Supabase has a generous free tier that covers personal use. You only need to upgrade to Pro ($25/month) if you hit the free tier’s row or bandwidth limits. HQ hosted provisions and manages the database for you automatically.

​
Create the project

1

Sign up and create a project

Go to supabase.com, create an account, and click New project. Choose a name, a strong database password (save it somewhere), and the region closest to you. Provisioning takes about 2 minutes.
2

Run the migrations

HQ needs 34 SQL migration files applied in order.
Recommended: The onboarding wizard offers a one-click schema install that applies all migrations automatically — no SQL Editor needed. Just connect your Supabase project in the browser and the wizard handles the rest.
If you prefer to run them manually, open SQL Editor in your Supabase dashboard:
  1. Browse to db/migrations/ on GitHub
  2. Open 001_extensions.sql, copy the SQL
  3. Paste into the SQL Editor, click Run
  4. Repeat for each file in filename order
Run the files in order. Later migrations reference tables created by earlier ones.
3

Create an auth user

Go to Authentication → Users and click Add user → Create new user. Enter an email and password — this is your HQ login. Check Auto Confirm User so you can sign in without email verification.
This is a Supabase auth user, not a Supabase account. Your Supabase account is how you manage the project; this user is how you log in to HQ itself.
4

Disable public signup

Go to Authentication → Providers → Email and toggle off Enable email signup.HQ grants authenticated users full access to all workspace data. Leaving signup open means anyone who can reach your HQ URL can create an account and see everything.
5

Copy your API keys

Go to Project Settings → API (gear icon → API in the left sidebar). You need three values:

Project URL

Looks like https://xxxx.supabase.co. This is how HQ finds your project.

Anon public key

A long JWT string under “Project API keys”. Safe to use in the browser.

Service role key

Another JWT under “Project API keys” — marked “secret”. Gives full database access. Treat like a password.
Keep this page open while you complete the HQ onboarding screen.

​
What HQ stores in your project

Workspace data

Contacts, organizations, tasks, knowledge items, routines, collections, notifications, and audit log.

Agent coordination

Agent definitions, commands, inbox items, heartbeats, and gateway registrations.

Usage and budgets

Per-agent LLM token usage, cost estimates, and monthly budget rollups.

Auth

User sessions and JWTs. HQ’s auth is Supabase auth — no separate account system.

​
Multiple workspaces

One HQ UI can manage multiple Supabase projects. This is useful for keeping client workspaces, personal workspaces, or staging environments completely separate. Switch workspaces from the workspace switcher in the top navigation. Each workspace is fully isolated — separate agents, data, gateways, and auth users. To add a second workspace: Settings → Database → Add workspace and paste the creds for the new Supabase project.

​
Supabase free tier limits

The free tier is sufficient for personal use. If you hit limits, you’ll see errors in the UI.
LimitFree tierWhen you might hit it
Database size500 MBLarge document or CRM datasets
Bandwidth5 GB / monthHeavy file storage or large exports
Realtime messages2 million / monthVery active agent fleets
Auth usersUnlimitedRarely a constraint — self-hosted installs typically have few users
Continue with Installation →