Development

Setting up a local development environment for HQ.

Prerequisites

Docker + Docker Compose
Node.js 24 (UI)
Git
A Supabase project for testing (a free one is fine)

On macOS: brew install node@24 docker (or install Docker Desktop). On Ubuntu: curl -fsSL https://get.docker.com | sudo sh and install Node from nodesource.

Clone and setup

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

Fill in .env:

SUPABASE_URL — optional override for gateway services. Leave empty to use browser onboarding.
SUPABASE_SERVICE_ROLE_KEY — optional override for gateway services. Leave empty to use browser onboarding.
WORKSPACE_SLUG — any slug, e.g. dev
GATEWAY_AUTH_TOKEN — generate with openssl rand -hex 32

Run the migration in your Supabase project:

Open Supabase Studio → SQL Editor
Run every file in db/migrations/ in filename order
Confirm the schema now has the core tables plus agent_usage, agent_budgets, and agents.reports_to_id

Create an auth user: Supabase → Authentication → Users → Add user (check “Auto Confirm User”).

Run the stack in dev mode

Live-reload overlay mounts source directories so changes pick up without rebuilding:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

UI at http://localhost:3000
Gateway’s noVNC at http://localhost:6901/vnc.html
Logs stream to stdout

Changes under apps/ui/ reload automatically. Changes to gateway/entrypoint.sh or the daemons require a restart:

docker compose restart gateway dispatcher runner

Working on just the UI

If you only touch UI code and don’t need a gateway, run Next.js directly:

cd apps/ui
npm install --legacy-peer-deps
npm run dev

Create apps/ui/.env.local:

SUPABASE_SERVICE_ROLE_KEY=...
GATEWAY_AUTH_TOKEN=...

Then either complete browser onboarding against the dev server or set HQ_CONFIG_DIR to a local directory containing compatible workspaces.json and secrets.json files. Pages that depend on a gateway will error if no gateway is running — expected.

Working on just the gateway

docker compose up -d gateway dispatcher runner
docker compose logs -f gateway

UI won’t be running, so you drive the gateway via direct Supabase inserts or docker compose exec.

Project structure

yourhq/
├── apps/ui/                    # Next.js app
│   ├── src/app/                # App Router pages + server actions
│   ├── src/components/         # React components (shadcn-based)
│   ├── src/hooks/              # Custom hooks
│   ├── src/lib/                # Supabase clients, types, utilities
│   ├── src/middleware.ts       # Auth guard
│   └── scripts/                # Build-time template index generator
├── gateway/
│   ├── Dockerfile              # Gateway image
│   ├── entrypoint.sh           # Container boot sequence
│   ├── files_api.py            # Files-API (Python stdlib HTTP server)
│   ├── daemons/                # inbox_dispatcher.py, command_runner.py
│   ├── dispatcher/Dockerfile
│   ├── runner/Dockerfile
│   ├── scripts/                # Shell helpers (add-agent.sh, etc.)
│   └── xfce-defaults/          # XFCE theme XMLs
├── templates/                  # Agent templates (one dir each)
├── db/migrations/              # Ordered SQL migrations
├── installer/install.sh        # The curl | bash target
├── docker-compose.yml          # Production stack
├── docker-compose.dev.yml      # Live-reload overlay
└── .github/workflows/          # CI and image publishing

Common tasks

Rebuild the UI image after a dependency change

docker compose build --no-cache ui
docker compose up -d ui

Needed when you add npm packages or change build-time UI behavior. Supabase browser config is runtime-injected from the workspace registry, so changing Supabase connections does not require an image rebuild.

Reset the gateway state

docker compose down -v  # DELETES the gateway-state volume — per-agent git branches, Chrome profile, etc.
docker compose up -d

Use sparingly. Better: start a fresh Supabase project + a fresh Compose project name (COMPOSE_PROJECT=yourhq-test) in .env so you don’t destroy your real data.

Add a dependency to the UI

cd apps/ui
npm install <package> --legacy-peer-deps

Commit package.json and package-lock.json. CI will use the lock.

Run linting / type-checking

cd apps/ui
npx tsc --noEmit      # zero errors expected
npm run lint          # warnings ok, errors fail CI

Run shellcheck

shellcheck gateway/entrypoint.sh gateway/scripts/*.sh installer/install.sh

Shellcheck also runs in CI (severity: warning).

Tests

Today there’s no automated test suite — CI runs typecheck + lint + shellcheck only. Contributions of test infrastructure welcome. For manual testing, see Troubleshooting for known failure modes to verify against.

Publishing images

CI publishes ghcr.io/yourhq/yourhq-{ui,gateway,dispatcher,runner}:latest on every push to main, and versioned tags on v* git tags. To cut a release:

git tag v0.x.y
git push origin v0.x.y

The docker-publish.yml workflow’s type=semver rule publishes :0.x.y tags automatically.

Getting help

Questions: GitHub Discussions
Bugs: GitHub Issues
Security: see SECURITY.md

Start here

Hosted

Self-host

Use Your HQ

Concepts

Design

Reference

Development

Security and troubleshooting

Local development

Development

Prerequisites

Clone and setup

Run the stack in dev mode

Working on just the UI

Working on just the gateway

Project structure

Common tasks

Rebuild the UI image after a dependency change

Reset the gateway state

Add a dependency to the UI

Run linting / type-checking

Run shellcheck

Tests

Publishing images

Getting help

​Development

​Prerequisites

​Clone and setup

​Run the stack in dev mode

​Working on just the UI

​Working on just the gateway

​Project structure

​Common tasks

​Rebuild the UI image after a dependency change

​Reset the gateway state

​Add a dependency to the UI

​Run linting / type-checking

​Run shellcheck

​Tests

​Publishing images

​Getting help

Development

Prerequisites

Clone and setup

Run the stack in dev mode

Working on just the UI

Working on just the gateway

Project structure

Common tasks

Rebuild the UI image after a dependency change

Reset the gateway state

Add a dependency to the UI

Run linting / type-checking

Run shellcheck

Tests

Publishing images

Getting help