Skip to main content
A gateway is a Docker host that runs agents. One HQ workspace can have multiple gateways — different machines, different geos, all coordinated through the same Supabase project.

​
Why add another gateway?

  • Run agents on a more powerful machine (e.g., a cloud VPS) while keeping the UI on a laptop
  • Split agents across hosts by role (e.g., research agents on one server, writing agents on another)
  • Keep a development gateway separate from your production one
  • Add a gateway in a different region for latency-sensitive work
1

Open Gateway settings

Go to Settings → Gateways in the left sidebar.
2

Click Add Gateway

Click + Add Gateway. A dialog opens.
3

Fill in the details

  • Label — a friendly name for this gateway (e.g. “Home Mac mini”, “Hetzner VPS”)
  • Tailscale auth key (optional) — if you want this gateway’s host to join your tailnet automatically, paste a Tailscale auth key here. Leave blank to configure Tailscale separately.
4

Copy the installer command

HQ mints a single-use registration token and generates a curl | bash installer command pre-loaded with your Supabase credentials and the token. The command looks like:
curl -fsSL https://install.yourhq.ai/gateway \
  | GATEWAY_TOKEN='...' SUPABASE_URL='...' \
    SUPABASE_ANON_KEY='...' SUPABASE_SERVICE_ROLE_KEY='...' \
    GATEWAY_LABEL='my-gateway' bash
Click Copy.
The token is shown once and valid for 15 minutes. HQ stores only a hash — not the plaintext. If it expires, close the dialog and start over to generate a new one.
5

Run the command on the new host

SSH into the new machine and paste the command. The installer (install.yourhq.ai/gateway) checks for Docker, writes .env, pulls the gateway images, and starts the stack. The gateway registers itself in your Supabase project using the token.
If you prefer to inspect the script before running it, download it first:
curl -fsSL https://install.yourhq.ai/gateway -o install-gateway.sh
bash install-gateway.sh
When run without env vars, the script prompts for each required value interactively.
6

Wait for the gateway to appear

Keep the dialog open. Within ~60 seconds, the new gateway row will appear in the list with a green heartbeat. If it doesn’t appear after 2 minutes, check the logs on the new host:
docker compose logs -f gateway
Look for registered (reachable at http://...) — that confirms success.

​
Manual registration

Use this for development setups, unusual deployment layouts, or if you want full control over the configuration.
1

Clone the repo on the gateway host

git clone https://github.com/yourhq/yourhq.git
cd yourhq
cp .env.example .env
2

Configure .env

Edit .env and set these values:
GATEWAY_ID=my-second-gateway          # must be unique across your workspace
SUPABASE_URL=https://xxxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...
HOST_REACHABLE_URL=http://100.x.y.z   # how the UI reaches this gateway
Leave GATEWAY_TOKEN unset — manual registration skips the token exchange.
3

Start the gateway services

docker compose up -d gateway dispatcher runner
The gateway upserts itself into the gateways table in Supabase and starts heartbeating every 30 seconds.
4

Verify in the UI

Go to Settings → Gateways. The new gateway should appear with a green heartbeat. If it shows “Stale” or doesn’t appear, check:
  • SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are correct
  • Migrations are complete (all 25 files in db/migrations/ have been run)
  • The host can reach Supabase: curl $SUPABASE_URL/rest/v1/ from inside the container
  • Gateway logs: docker compose logs gateway | tail -50

​
Assigning agents to a specific gateway

When you create a new agent, HQ asks which gateway it should run on. The agent’s gateway_id is set at creation time. To move an agent to a different gateway, delete and recreate it — agents are provisioned into a specific gateway’s file system and can’t be migrated live.

​
Troubleshooting

Gateway appears but shows “Stale” heartbeat: The runner daemon has likely stopped. Check: docker compose logs -f runner | tail -50. Restart: docker compose restart runner. Gateway registered but agents won’t provision: The dispatcher or runner may not be running. Check all services: docker compose ps. If any show Restarting, tail their logs. Token expired before you ran the command: Close the Add Gateway dialog and open it again — this generates a fresh token with a new 15-minute window. See also Operations →, Gateway boot sequence →