Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yourhq.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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. Open SQL Editor and run every .sql file in db/migrations/ in filename order (001 through 017). Each file is named descriptively. The onboarding wizard handles this automatically if you set up through the browser.
  4. Go to Authentication → Users → Add user (check “Auto Confirm User”). Remember the email/password.
  5. Go to Project Settings → API. Copy three values:
    • Project URL
    • Anon public key
    • Service role key (the secret one)

​
(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. Asks which networking mode you want:
    • Local-only (default) — HQ is reachable only on this machine.
    • Tailscale — installs Tailscale on the host; reachable from any device on your tailnet.
    • Public HTTPS — advanced; requires you to set up a reverse proxy (Caddy, nginx, etc.) yourself. HQ does not bundle one.
  3. If you pick Tailscale, asks for your auth key and optionally an exit node.
  4. Optionally asks for GitHub sync creds (skip to run without git remote).
  5. Writes .env, pulls images from GHCR, runs docker compose up -d (full stack: UI + gateway + dispatcher + runner).
  6. Opens your browser to http://localhost:3000.
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
Same outcome as Path 1 without the interactive prompts. Best when you already have Tailscale set up and don’t need the installer to do it for you.

​
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 setup wizard (workspace name, pipeline stages, custom fields, task streams).
  4. Authenticate at least one model provider from Settings → Connections. API-key providers can be added directly. Interactive providers show the login URL or device flow in the UI and complete through the command runner.
  5. Create your first agent: Agents → New Agent → pick a template → name → choose a messaging channel (Telegram, Discord, Slack, or None) → enter credentials → Create.
  6. For Telegram or Discord: 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 in your workspace immediately. Next message triggers the agent.

​
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. Run the generated one-line installer on the gateway host.
  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 up -d gateway dispatcher runner (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 or 6901 on your host. Change UI_HOST_PORT / NOVNC_HOST_PORT in .env.
  • Setup wizard 500s on “Complete setup”: 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: you haven’t run all migrations. Run every file in db/migrations/ in filename order and retry.
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 project 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.