Skip to main content

​
Installation

HQ can run on one machine or across multiple machines. Start simple: one Docker host, one Supabase project, one gateway.

Fastest path

Use the installer and finish setup in the browser.

Inspect first

Clone the repo and run Docker Compose yourself.

Develop locally

Use the development overlay for live UI reloads.

​
TL;DR

On any Linux or macOS host with Docker: 
curl -fsSL install.yourhq.ai | bash
The installer asks a few questions, runs Docker Compose, and opens your browser. Most setup happens in the UI. The rest of this doc covers prerequisites, the different install paths, and how to deploy across multiple machines.

​
Prerequisites

​
Docker

​
Supabase

You need a Supabase project before running the installer.
  1. Sign up at supabase.com (free tier is fine for personal use).
  2. Create a new project. Wait ~2 minutes for provisioning.
  3. Go to Project Settings → API. Copy three values:
    • Project URL
    • Anon public key
    • Service role key (the secret one)
You do not need to run the SQL migrations manually. The onboarding wizard in the browser detects a fresh database and offers a one-click schema install that applies all migrations automatically. See Supabase setup if you prefer to run them by hand.

​
(Optional) Tailscale

If you plan to access HQ from a second device (phone, laptop, another machine), sign up for Tailscale before installing. Generate a reusable auth key at login.tailscale.com/admin/settings/keys and paste it when the installer asks.

​
Paths

curl -fsSL install.yourhq.ai | bash
The installer:
  1. Checks that Docker is present; prompts to install it if not (Linux only).
  2. Optionally asks for GitHub sync creds (skip to run without git remote).
  3. Writes .env, pulls the UI image from GHCR, and runs docker compose up -d ui.
  4. Opens your browser to http://localhost:3000.
The installer only starts the UI. Gateway services (agents, dispatcher, runner, embedder, file processor) are started later — either on the same machine or a remote host — through the onboarding wizard in the browser. This keeps the initial download small (~200 MB) and lets you choose where to run agents. When you first load the UI, you’ll see the Connect Supabase onboarding screen. Paste your URL + anon key + service role key there. On success, sign in with the Supabase auth user you created, and you’re in. The gateway services are already running and waiting — they auto-pick up your Supabase creds from the shared registry the moment you finish onboarding. No second install step. On a fresh machine: about 5 minutes. Most of that is image pulls. 
git clone https://github.com/yourhq/yourhq.git
cd yourhq
cp .env.example .env
# edit .env with your Supabase URL + keys, set GATEWAY_AUTH_TOKEN=$(openssl rand -hex 32)
docker compose up -d ui                          # UI only
docker compose --profile gateway up -d            # add gateway services on the same host
Same outcome as Path 1 without the interactive prompts. Use --profile gateway to start the agent runtime alongside the UI.

​
Path 3: development mode

For contributors — live-reload the UI as you edit source: 
git clone https://github.com/yourhq/yourhq.git
cd yourhq
cp .env.example .env
# edit .env
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
UI reloads on file changes under apps/ui/. See Local development for full dev setup.

​
After install

  1. Open http://localhost:3000 in your browser.
  2. Log in with the Supabase auth user you created.
  3. Complete the onboarding wizard — it walks you through workspace identity, use case, infrastructure connection (Supabase + gateway), model provider (BYO API key), and first agent creation in one flow. See Workspace setup for details.
  4. For Telegram or Discord agents: send your bot a DM — it replies with a pairing code. Paste it into the agent’s detail page. For Slack: the agent is active immediately.

​
Multi-machine setups

​
Splitting UI and gateway across machines

HQ includes UI-driven gateway registration. The manual process still works, but most users should use Settings → Gateways → Add Gateway. Recommended process:
  1. On the UI host: run the installer normally.
  2. Open Settings → Gateways → Add Gateway.
  3. Enter a label and, optionally, a Tailscale auth key.
  4. Copy the generated one-line installer and run it on the gateway host: 
    curl -fsSL https://install.yourhq.ai/gateway \
  | GATEWAY_TOKEN='...' SUPABASE_URL='...' ... bash
    The installer checks for Docker, writes .env, pulls images, and starts the gateway. If you prefer to inspect the script first, download it with curl -fsSL https://install.yourhq.ai/gateway -o install-gateway.sh and run it manually — it will prompt for any missing values.
  5. Keep the dialog open until the registration token is consumed and the gateway appears.
Manual process:
  1. On the UI host: run the installer normally (Tailscale mode recommended).
  2. On the gateway host: clone the repo, copy .env, and set:
    • A unique GATEWAY_ID (e.g. mac-mini, vps-eu)
    • The same SUPABASE_URL + keys as the UI host
    • GATEWAY_AUTH_TOKEN matching the UI’s
  3. On the gateway host: install Tailscale and join the same tailnet as the UI host.
  4. Set HOST_REACHABLE_URL=http://<gateway-host-tailscale-ip> in the gateway’s .env.
  5. docker compose --profile gateway up -d (skip ui).
  6. The gateway registers itself in Supabase’s gateways table. The UI sees it within 30 seconds.
See Networking for the networking model and topology diagrams.

​
Troubleshooting install

  • “Docker is not installed” on macOS/Windows: install Docker Desktop (GUI app), not the Linux installer.
  • UI shows the onboarding screen every time I load it: the ui-config volume got wiped or isn’t persisting. Check docker volume inspect yourhq-ui-config and re-complete onboarding.
  • “Pull access denied” on GHCR: only relevant if the repo is private. docker login ghcr.io -u <your-gh-user> with a PAT that has read:packages scope.
  • docker compose up fails with “port already in use”: something else is on port 3000 on your host. Change UI_HOST_PORT in .env.
  • Onboarding wizard 500s: CSRF origin mismatch. Set ALLOWED_ORIGINS in .env to match the host you’re accessing from. Restart the UI.
  • Onboarding validator says a table/function doesn’t exist: the schema is incomplete. Re-run the one-click schema install from the onboarding wizard, or manually apply every file in db/migrations/ in filename order.
See Troubleshooting for more.

​
Updating

cd ~/.yourhq  # or wherever you installed
git pull       # if you cloned
docker compose pull
docker compose up -d
UI Supabase config lives in the workspace registry (no rebuild needed after updates). Only pull and restart.

​
Uninstalling

cd ~/.yourhq
docker compose down -v    # DELETES volumes — all agent state gone
cd ..
rm -rf .yourhq
Also: go to your Supabase dashboard and delete the project.