Skip to main content
Not technical? That’s fine. The install is one command in a terminal and a few steps in your browser. You don’t need to edit code or understand Docker to get started. Or skip infrastructure entirely with HQ hosted.

​
Before you begin

You need three things. All are free to start.

Docker

Runs everything locally. Download Docker Desktop for Mac or Windows. On Linux, the installer handles it.

Supabase account

Free at supabase.com. This is where your workspace data lives — on your own account.

Model API key

Any provider works. OpenAI and Anthropic are the most common. You’ll add this during the onboarding wizard.
Want to access HQ from your phone or another laptop? Sign up for Tailscale (free) before installing and the installer will configure it for you.

​
Step 1 — Create a Supabase project

1

Create a project

Go to supabase.com, sign in, and create a new project. Choose any name and region. Wait about 2 minutes for it to provision.
2

Create an auth user

Go to Authentication → Users in your Supabase dashboard. Click Add user → Create new user. Enter an email and password — this is what you’ll use to log in to HQ. Check “Auto Confirm User” so you can sign in immediately.
3

Disable public signup

Go to Authentication → Providers → Email and turn off “Enable email signup”. This prevents strangers from creating accounts in your workspace — only the user you just created can log in.
4

Copy your API keys

Go to Project Settings → API (gear icon in the left sidebar). You’ll need three values — keep this tab open:
KeyWhere to find itWhat it’s for
Project URLTop of the API pageHow HQ finds your Supabase project
Anon public keyUnder “Project API keys”Public identifier (safe to share)
Service role keyUnder “Project API keys” (secret — don’t share)Master key with full database access — treat like a password
The service role key bypasses all security policies and has full access to your database. Treat it like a password.

​
Step 2 — Install HQ

Open a terminal on your Mac or Linux machine (on Windows, use WSL — Windows Subsystem for Linux) and run: 
curl -fsSL install.yourhq.ai | bash
The installer will ask you a couple of questions:
  1. GitHub sync — optional backup for agent files. Skip for now (press Enter) — you can enable it later in Settings.
It pulls Docker images (~1.5 GB on first run — this takes a few minutes), starts the stack, and opens your browser.
Prefer to inspect the code first? Clone the repo and run it manually:
git clone https://github.com/yourhq/yourhq.git
cd yourhq
cp .env.example .env
docker compose up -d ui

​
Step 3 — Complete the onboarding wizard

Your browser opens to http://localhost:3000. Sign in with the email and password you created in Step 1, then the onboarding wizard walks you through everything in one flow:
1

Welcome

Enter your name and confirm your workspace name (auto-generated, editable).
2

Intent

Pick what you’ll use HQ for — outreach, deals, hiring, publishing, ops, or exploring. This seeds a recommended agent template and workspace context.
3

Infrastructure

Paste the three Supabase values you copied in Step 1 (Project URL, anon key, service role key). Then choose where to run your gateway — “This machine” (Docker, already running) or “Remote server” (copy a one-liner to another host).HQ validates the database connection, installs the schema automatically if needed, and waits for the gateway to come online.
4

Model provider

Choose Anthropic, OpenAI, or Ollama and enter your API key. HQ validates it inline. For Ollama, it auto-detects the local instance — just make sure Ollama is running.
5

First agent

HQ recommends an agent based on your intent. Customize the name and emoji if you’d like, then create it. Optionally connect a messaging channel (Telegram, Discord, Slack) to talk to your agent via DM.
After creation, you land on the Tasks page with a suggested first task pre-filled.
If you see a “table does not exist” error during the infrastructure step, the one-click schema install may not have completed. Re-run it from the onboarding wizard, or manually apply the migration files from db/migrations/ in the Supabase SQL Editor. See Supabase setup for details.

​
You’re set up

Your HQ is running with a connected database, model provider, and first agent.
Putting this on the internet? The default install binds services to 127.0.0.1 — safe on a laptop. The runner mounts the Docker socket (so it can restart the stack from the UI), and your Supabase service-role key sits in .env with full database access. Read the security policy and hardening guide before exposing HQ beyond localhost.
Here’s what to explore next:

Pick a model per agent

Assign different models and thinking levels to each agent. Mix cheap and expensive models across your fleet.

Understand agents

Memory, files, skills, org chart, and how agents actually work.

Set usage budgets

Avoid surprise API bills with per-agent monthly limits.

Access from other devices

Set up Tailscale so your phone and laptop can reach HQ.

Troubleshooting

Something didn’t work? Common fixes are here.