> ## 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.

# FAQ

> Common questions about HQ — what it is, how it works, and how to run it.

<AccordionGroup>
  <Accordion title="What is HQ?">
    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.
  </Accordion>

  <Accordion title="How long does it take to get started?">
    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 →](/getting-started/quickstart)
  </Accordion>

  <Accordion title="Do I need to know how to code?">
    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.
  </Accordion>

  <Accordion title="Is there a hosted version?">
    Yes. Sign up at [app.yourhq.ai](https://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 →](/hosted/getting-started)
  </Accordion>

  <Accordion title="Why self-host instead of using hosted?">
    * **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](/hosted/getting-started).
  </Accordion>

  <Accordion title="Why the name &#x22;HQ&#x22;?">
    It's the headquarters metaphor — one place where you manage everything. Short, memorable, hard to misspell.
  </Accordion>

  <Accordion title="Is this just a wrapper around OpenClaw / ChatGPT?">
    No. OpenClaw is the agent *runtime* — it handles the inner loop of executing prompts and tool calls. HQ (v0.2.2, running OpenClaw 6.6) is the *operations layer* around it: provisioning, lifecycle management, queues, knowledge base, CRM, tasks with subtask support, routines, budgets, plugins, 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.
  </Accordion>

  <Accordion title="How does this compare to CrewAI, OpenAI Agents SDK, or n8n?">
    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 →](/concepts/why-hq) for the full comparison.
  </Accordion>

  <Accordion title="Can I rip out the CRM / tasks / knowledge and just use the agents?">
    The workspace modules (CRM, tasks with subtasks, knowledge, collections) are tightly integrated — agents reference contacts, create tasks and subtasks, search knowledge across scopes (workspace, agent, and library), 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.
  </Accordion>

  <Accordion title="What's the catch with the hosted version?">
    \$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.
  </Accordion>
</AccordionGroup>

***

## Agents & models

<AccordionGroup>
  <Accordion title="What is an agent?">
    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.
  </Accordion>

  <Accordion title="What models can agents use?">
    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 →](/guides/connect-model-provider)
  </Accordion>

  <Accordion title="Can I use a free / local model?">
    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 →](/guides/connect-model-provider)
  </Accordion>

  <Accordion title="Can I use different models for different agents?">
    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.
  </Accordion>

  <Accordion title="Can agents see each other and collaborate?">
    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 →](/guides/automations)
  </Accordion>

  <Accordion title="What happens when an agent hits its budget limit?">
    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 →](/guides/usage-budgets)
  </Accordion>

  <Accordion title="Do tasks support subtasks?">
    Yes (v0.2.2+). Tasks can have one level of subtasks. You can create subtasks inline from the task detail modal, toggle their status independently, and see a progress bar (done/total) on the parent task. List and board views show subtask progress chips. The nesting is intentionally limited to one level to keep things simple.

    See [Tasks →](/concepts/tasks-inbox-and-commands)
  </Accordion>

  <Accordion title="How does knowledge scoping work?">
    Knowledge items have three scopes:

    * **Workspace** — visible to all agents in the workspace. Good for company-wide context, SOPs, and reference material.
    * **Agent** — scoped to a specific agent via the knowledge-agent junction table. Only that agent sees it in its context.
    * **Library** — workspace-wide shared context (v0.2.2+). Library items are available for reference across the workspace without being injected into every agent's boot context.

    Each scope determines who sees the item and how it's surfaced during agent execution. Items can be pages, skills, files, or source-synced content.

    See [Knowledge →](/concepts/knowledge)
  </Accordion>

  <Accordion title="What agent templates are included?">
    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-writer`

    Each 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 →](/reference/templates)
  </Accordion>

  <Accordion title="Can I write my own agent template?">
    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 →](/concepts/agents)
  </Accordion>
</AccordionGroup>

***

## Self-hosting & operations

<AccordionGroup>
  <Accordion title="What hardware do I need?">
    **Minimum:** Any machine with 4 GB RAM and Docker. A t3.medium on AWS (\~$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.
  </Accordion>

  <Accordion title="Does HQ need internet access?">
    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.
  </Accordion>

  <Accordion title="Can I run multiple gateways?">
    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 →](/self-host/add-gateway)
  </Accordion>

  <Accordion title="Can I run multiple workspaces?">
    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.
  </Accordion>

  <Accordion title="Can I run HQ on a Raspberry Pi?">
    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.
  </Accordion>

  <Accordion title="How do I reach HQ from my phone?">
    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](/self-host/networking))

    See [Networking →](/self-host/networking)
  </Accordion>

  <Accordion title="How do I update HQ?">
    ```bash theme={null}
    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**.

    <Warning>
      If a new release includes database migrations, run them in the Supabase SQL Editor **before** pulling new images. Check the [GitHub releases page](https://github.com/yourhq/yourhq/releases) first.
    </Warning>
  </Accordion>

  <Accordion title="How do I back up my data?">
    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 →](/self-host/operations)
    2. **Gateway state** — auth tokens, agent configs, secrets, and Telegram pairing. Since v0.2.1, gateways **automatically back up to Supabase Storage** on shutdown and restore on fresh boot. You can also trigger a manual backup from **Settings → Backups**. Retention: 5 backups per gateway, 7-day max age.
    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.
  </Accordion>

  <Accordion title="How are gateway backups handled?">
    Gateway backup and restore is built in (v0.2.1+). On shutdown (SIGTERM), the gateway automatically packages its state — auth tokens, agent configs, encrypted secrets, Telegram pairing — into a tarball and uploads it to Supabase Storage. On a fresh boot with no local state, the gateway downloads and restores the latest backup automatically.

    You can also:

    * **Trigger a manual backup** from **Settings → Backups** in the UI
    * **View backup status** per gateway, including last backup time and size
    * **Delete old backups** from the UI

    Retention is 5 backups per gateway with a 7-day max age. If the newest backup is corrupt, restore falls back to the next available one.

    This means ephemeral gateways (like E2B sandboxes) can shut down and come back with full state intact.
  </Accordion>

  <Accordion title="How do I uninstall?">
    ```bash theme={null}
    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.

    <Warning>
      `docker compose down -v` is irreversible. Back up the gateway state volume first if you want to keep anything.
    </Warning>
  </Accordion>

  <Accordion title="What does it cost to run?">
    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–$100/month per active agent depending on the provider and how much work the agent does. Use Ollama to eliminate API costs entirely.
  </Accordion>
</AccordionGroup>

***

## Data & security

<AccordionGroup>
  <Accordion title="Who can see my data?">
    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).
  </Accordion>

  <Accordion title="How is multi-tenancy handled?">
    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 →](/concepts/security-model)
  </Accordion>

  <Accordion title="How do I report a security issue?">
    Email `security@yourhq.ai`. Do not open a public GitHub issue for security vulnerabilities.

    See [Security policy →](/security/security-policy)
  </Accordion>

  <Accordion title="Is my service role key safe?">
    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.
  </Accordion>
</AccordionGroup>

***

## Customization & development

<AccordionGroup>
  <Accordion title="Can I customize the UI?">
    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.
  </Accordion>

  <Accordion title="Can I add my own agent templates?">
    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 →](/reference/templates)
  </Accordion>

  <Accordion title="Can I add custom routines or triggers?">
    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 →](/reference/inbox-dispatch)
  </Accordion>

  <Accordion title="How do I contribute?">
    * Read [Contributing →](/development/contributing) for the PR process
    * Bug reports: [GitHub Issues](https://github.com/yourhq/yourhq/issues)
    * Design questions, roadmap: [GitHub Discussions](https://github.com/yourhq/yourhq/discussions)
    * Security issues: `security@yourhq.ai` only

    Local development setup is in [Local development →](/development/local-development).
  </Accordion>

  <Accordion title="Who uses HQ?">
    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.
  </Accordion>
</AccordionGroup>