> ## 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
# Installation
HQ can run on one machine or across multiple machines. Start simple: one Docker host, one Supabase project, one gateway.
Use the installer and finish setup in the browser.
Clone the repo and run Docker Compose yourself.
Use the development overlay for live UI reloads.
## TL;DR
On any Linux or macOS host with Docker:
```bash theme={null}
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
* **Linux**: the installer auto-installs Docker for you via `get.docker.com` if it's missing.
* **macOS**: [download Docker Desktop](https://docs.docker.com/desktop/install/mac-install/) first.
* **Windows**: install [WSL2](https://learn.microsoft.com/windows/wsl/install) + [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/), then run the installer from a WSL shell.
### Supabase
You need a Supabase project before running the installer.
1. Sign up at [supabase.com](https://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](/self-host/supabase) 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](https://tailscale.com) before installing. Generate a reusable auth key at [login.tailscale.com/admin/settings/keys](https://login.tailscale.com/admin/settings/keys) and paste it when the installer asks.
## Paths
### Path 1: one-line install (recommended for most users)
```bash theme={null}
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.
### Path 2: clone and run (recommended for developers)
```bash theme={null}
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:
```bash theme={null}
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](/development/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](/guides/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:
```bash theme={null}
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://` 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](/self-host/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 ` 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](/troubleshooting/common-issues) for more.
## Updating
```bash theme={null}
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
```bash theme={null}
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.