Skip to main content
HQ is an open-source platform for running AI agents on your own infrastructure. You bring a Docker host and a free Supabase account; HQ gives you the UI, the agent runtime, a CRM, a task system, and a library of agent templates.Agents have real memory, can browse the web, use tools, manage files, and respond through messaging channels (Telegram, Discord, Slack). They’re not chat bots — they run as persistent processes that do background work on your behalf.
About 10 minutes:
  • ~2 min to create a Supabase project and an auth user
  • ~5 min for Docker to pull images on first run (~1.5 GB)
  • ~2 min to connect your model provider and create the first agent
The onboarding wizard runs database migrations and handles setup automatically — no manual SQL needed.See the Quickstart →
No. The install is a single curl | bash command. Everything else — Supabase setup, agent creation, routines — is done through the UI. You don’t need to edit any code or understand Docker internals to get started.If you want to customize agent templates, build your own, or contribute to the project, coding knowledge helps — but it’s entirely optional.
Yes. Sign up at app.yourhq.ai and skip the self-hosting entirely — we handle the database, agent runtime, and updates. $30/month per workspace, ready in under 2 minutes.See Hosted getting started →
  • Your data stays on your machine. No third party has access to your CRM, knowledge, or agent outputs.
  • Free. You only pay for your own infrastructure and model API costs.
  • Open source. Fork it, customize it, ship your own version.
  • Offline-capable. Gateways can run on a laptop or home server with no cloud dependency.
  • Full template control. Modify agent templates directly on the filesystem.
The trade-off: you’re responsible for updates, backups, and debugging. If that’s unappealing, try the hosted version.
It’s the headquarters metaphor — one place where you manage everything. Short, memorable, hard to misspell.
No. OpenClaw is the agent runtime — it handles the inner loop of executing prompts and tool calls. HQ is the operations layer around it: provisioning, lifecycle management, queues, knowledge base, CRM, tasks, routines, budgets, and the entire UI. Think of OpenClaw as the engine and HQ as the car, dashboard, and garage.HQ is also model-agnostic — it works with any provider (OpenAI, Anthropic, Gemini, Ollama, etc.), not just one.
Short answer: different shapes for different problems.
  • CrewAI / OpenAI Agents SDK are code frameworks — you write Python to orchestrate agents for a specific task. If you want to embed agents into an existing app, use those.
  • n8n is a workflow builder — visual editor, hundreds of SaaS integrations, trigger-action patterns. If your problem is “when X happens, do Y in Z,” use n8n.
  • HQ is a product — a self-hosted workspace your team logs into. Agents persist across days with memory, files, and identity. CRM, tasks, knowledge, and routines are built in.
See Why HQ → for the full comparison.
The workspace modules (CRM, tasks, knowledge, collections) are tightly integrated — agents reference contacts, create tasks, search knowledge, and submit deliverables. You can ignore modules you don’t need (just don’t navigate to them), but removing them from the codebase would break the agent context system.If you want agents without the workspace, a framework like CrewAI is a better fit.
$30/month per workspace. We handle database provisioning, gateway hosting, updates, and backups. Your data lives in a Supabase project we provision for you — isolated per workspace, not shared. You can export and self-host at any time.The code is identical — hosted runs the same repo with DEPLOYMENT_MODE=hosted. No proprietary features, no lock-in.

​
Agents & models

An agent is a persistent workspace made up of:
  • A git branch — holds identity files, memory notes, skills, and docs
  • A Chrome profile — persistent cookies and logged-in browser sessions
  • A messaging channel — Telegram, Discord, Slack, or none
  • An OpenClaw session — the runtime that executes prompts and tool calls
Agents have real memory across sessions, can browse the web, send messages, edit files, and call APIs. They run as background processes, not just in response to messages.
HQ is model-agnostic. Agents use whatever provider you configure:
  • API key providers: OpenAI, Anthropic, Google Gemini, DeepSeek, Mistral, Groq, OpenRouter, and 15+ more
  • OAuth providers: OpenAI Codex, GitHub Copilot
  • Local / self-hosted: Ollama, LM Studio, vLLM, any OpenAI-compatible server
There is no default or required provider. You can set different models per agent, and override the model per task.See Connect a model provider →
Yes. Ollama lets you run models like Llama 3, Mistral, and Gemma entirely on your machine — no API costs, fully private. Install Ollama, pull a model, and point HQ at http://host.docker.internal:11434.Local models are slower and less capable than frontier models for complex tasks, but they’re free and work offline.See the Ollama walkthrough in Connect a model provider →
Yes. Each agent has its own model selector on its detail page, and you can override the model per task. A common pattern: use a frontier model (Claude Opus, GPT-4.1) for agents doing complex reasoning, and a cheaper model or Ollama for agents doing simple lookups.
Yes — agents share the same Supabase database, so tasks, contacts, knowledge items, and comments are all visible across agents.Collaboration patterns:
  • @-mentions: type @agent-slug in any task comment to wake that agent
  • Routines: set a routine so agent A’s output (a status change, new task, etc.) triggers agent B
  • Org chart: agents can be arranged into a manager/direct-report hierarchy. That hierarchy is injected into agent boot context and gives agents a clear delegation model
See Routines →
It depends on how you’ve configured it:
  • Soft threshold only — a notification fires when the agent crosses the warning percentage. The agent keeps working.
  • Hard cutoff enabled — the runtime blocks further LLM replies and the dispatcher stops waking the agent for background work. The agent is effectively paused until the next budget period (first of the month) or until you raise the limit.
See Usage budgets →
HQ ships 16 built-in templates:default, analytics, assistant, chief-of-staff, cmo, cofounder, crm-researcher, designer, ghostwriter, market-researcher, newsletter-editor, newsletter-writer, sales-copywriter, script-writer, social-strategist, social-writerEach template comes with pre-loaded identity files, skills, and a personality. You pick one when creating an agent — you can customize everything afterward.See Templates reference →
Yes. Copy templates/default/ to templates/your-role/, edit the identity files (IDENTITY.md, SOUL.md, USER.md, MEMORY.md), and add role-specific skills under skills/. The gateway picks up new templates automatically when it reboots.If your template might be useful to others, open a PR.See Agents →

​
Self-hosting & operations

Minimum: Any machine with 4 GB RAM and Docker. A t3.medium on AWS (~20/month)ortheequivalentHetznerCX22( 20/month) or the equivalent Hetzner CX22 (~4/month) works well.Resource usage per gateway:
  • Idle (1–2 agents): ~1.5 GB RAM, 5–10% CPU
  • Active agent (browsing/running): +~500 MB RAM, CPU spikes during work
Recommended minimums:
  • t3.small (2 GB RAM): absolute floor, 1 agent
  • t3.medium (4 GB RAM): comfortable for 2–3 active agents
  • t3.large / m5.large: heavier use, 5+ agents
Raspberry Pi 4/5 (arm64, 4–8 GB) works fine — arm64 images are published automatically.
The gateway needs internet for:
  • Model API calls (unless using Ollama or another local model)
  • Supabase connectivity (unless you self-host Supabase)
  • OpenClaw plugin updates
Gateway agents need internet to browse the web. Beyond that, a local model + self-hosted Supabase gives you a fully offline setup.
Yes. Each gateway registers itself with a unique GATEWAY_ID. Agents are bound to a specific gateway via a foreign key; the UI talks to each gateway via its stored reachable URL.Example: UI on your laptop, one gateway on a Mac mini at home, one gateway on a VPS — all pointing at the same Supabase database.To add a gateway: Settings → Gateways → Add Gateway. HQ generates a one-time registration token and gives you the installer command for the new host.See Add a gateway →
Yes. One HQ UI instance can manage multiple independent Supabase projects via the workspace registry. Use the workspace switcher in the top nav to switch between workspaces. Each workspace is completely isolated — separate agents, data, gateways, and auth users.You can also run multiple Compose stacks on the same host by setting a different COMPOSE_PROJECT in each .env — they get separate volumes and container names.
Yes. Raspberry Pi 4 or 5 (arm64) runs the full stack. The Pi 4 with 4 GB RAM is the minimum; Pi 5 with 8 GB is comfortable. arm64 images are built and published automatically — the installer handles it.
Several options, from simplest to most involved:
  1. Tailscale (recommended) — install Tailscale on both your phone and the HQ host, access via http://<host-tailscale-ip>:3000. Private, no port exposure.
  2. Tailscale Serve — sudo tailscale serve --bg --https=443 localhost:3000 → TLS access at https://hq.<tailnet>.ts.net
  3. Tailscale Funnel — makes HQ accessible from the internet without Tailscale on the phone
  4. Reverse proxy — Cloudflare Tunnel, nginx, Caddy, etc. (see Networking)
See Networking →
cd ~/.yourhq
docker compose pull
docker compose up -d
No rebuilds required — the UI reads its Supabase config from a runtime volume, not from the image.You can also trigger updates from the UI: Settings → Gateways → hover a gateway row → Update gateway.
If a new release includes database migrations, run them in the Supabase SQL Editor before pulling new images. Check the GitHub releases page first.
Three things to back up:
  1. Supabase — your contacts, tasks, agents, knowledge items, audit log. Use Supabase built-in backups (Pro tier) or pg_dump to a file. See Operations →
  2. Gateway state volume — per-agent git branches, Chrome profiles, OpenClaw config. Back up with docker run --rm -v yourhq-gateway-state:/src -v $(pwd):/dst alpine tar -czf /dst/gateway-state.tar.gz -C /src .
  3. .env — contains secrets. Store in a password manager or encrypted disk.
Optional: set GIT_REMOTE_URL in .env to continuously sync agent branches to GitHub/Gitea.
cd ~/.yourhq
docker compose down -v   # deletes containers AND volumes — all agent state gone
cd ..
rm -rf .yourhq
To also delete the database: Supabase dashboard → Settings → General → Delete project.
docker compose down -v is irreversible. Back up the gateway state volume first if you want to keep anything.
Infrastructure:
  • Laptop / home server: free
  • Hetzner CX22 (~2 vCPU, 4 GB RAM): ~$4/month
  • AWS t3.medium (2 vCPU, 4 GB RAM): ~$20/month
Supabase free tier covers small and personal use. Pro is $25/month if you hit the free tier limits.Model API costs vary widely: typically 10–10–100/month per active agent depending on the provider and how much work the agent does. Use Ollama to eliminate API costs entirely.

​
Data & security

Only you — and only if you set it up that way. HQ stores everything in your own Supabase project. Anthropic and the HQ maintainers have no access to your workspace data, your agent conversations, or your API keys.The only outbound connections are model API calls (to your chosen provider) and Supabase queries (to your own project).
HQ uses tenant-scoped row-level security on every table — each row has a tenant_id, and RLS policies restrict access to rows matching the authenticated user’s tenant. Self-hosted installs use a single default tenant. On top of that, the multi-workspace registry gives each workspace its own Supabase project for full database-level isolation. The UI’s workspace switcher lets one HQ instance manage multiple isolated workspaces.See Security model →
Email [email protected]. Do not open a public GitHub issue for security vulnerabilities.See Security policy →
The service role key is stored in the ui-config Docker volume on your host — never sent to or stored by Anthropic or the HQ maintainers. It’s included in .env for the gateway daemons that need direct database access.Treat it like a database password: don’t commit it to public repos, don’t share it in screenshots. If it leaks, regenerate it in Supabase → Settings → API.

​
Customization & development

Yes — fork the repo. apps/ui/ is a standard Next.js app (App Router, Tailwind CSS, shadcn components). Modify, rebuild, and deploy from your fork. Pull upstream changes at your own cadence.If your changes might benefit others, open a PR.
Yes. Copy templates/default/ to templates/your-role/ and edit the identity files. The gateway picks up new templates from /opt/templates/ at boot. Rebuild the gateway image with your templates included, or set TEMPLATES_SOURCE in .env to point at an external repo.See Templates reference →
The routine trigger types are defined in the UI and matched in the inbox dispatcher. Adding a new trigger type requires:
  1. A new entry in the routine trigger type enum (via a migration)
  2. A place in the UI or a backend hook that creates the agent_inbox_items row
  3. The dispatcher handles it automatically — it dispatches any actionable inbox item
See Inbox dispatch reference →
Local development setup is in Local development →.
Founders, solo operators, and small teams who want their AI agents to do real background work on their own infrastructure — not in a SaaS they don’t control. The project is early and growing; contributions and feedback from adopters shape the roadmap directly.