> ## 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.
# What HQ includes
> A practical tour of HQ's workspace, agents, gateways, routines, knowledge, CRM, and budgets.
HQ is an agent operations system, not just an agent chat UI. It gives you a workspace for CRM, tasks, knowledge, routines, collections, and a fleet of long-lived AI agents that run on infrastructure you control.
This page is the product tour. For system internals, read [Architecture](/concepts/architecture). For installation, read [Installation](/self-host/installation).
## At a glance
Long-lived workers with memory, browser profiles, templates, messaging channels, and tools.
Per-agent and per-task model + thinking level. Mix providers freely across your fleet.
CRM, tasks, knowledge, routines, collections, notifications, and activity.
Docker hosts that run agents on infrastructure you control.
Convert CRM, task, and comment events into agent work via schedule and event triggers.
Encrypted credential storage with per-agent scoping and automatic gateway sync.
Track model spend and stop agents when they exceed limits.
Extend HQ with event-driven integrations — local Python handlers or remote webhooks.
Inspect, fork, customize, and extend the whole system.
## Workspace
Every HQ install connects to one or more Supabase projects. A workspace contains all the data: agents, tasks, CRM records, knowledge, routines, collections, settings, gateway registrations, command history, and usage data.
The first boot flow is intentionally config-light:
1. Start the Docker stack (self-hosted) or sign up (hosted).
2. Open the UI and sign in.
3. Complete the onboarding wizard.
After setup, the workspace can be managed from Settings. Additional workspaces can be added from Settings → Workspaces — the "Add Workspace" flow has full parity with the initial onboarding wizard, including intent selection, infrastructure connection, model provider setup, and first agent creation.
The UI stores workspace metadata in `/config/workspaces.json` and workspace secrets in `/config/secrets.json` on the `ui-config` volume. The active workspace is selected at runtime, so the published UI image does not need a rebuild for each user's Supabase project.
## Onboarding
The onboarding wizard consolidates all first-boot setup into a single guided flow:
1. **Welcome** — workspace name and owner profile.
2. **Intent** — pick a use case (outreach, deals, hiring, publishing, ops, explore). Seeds a context preset with pipeline stages, fields, and streams.
3. **Infrastructure** (self-hosted only) — connect Supabase (URL + keys) and choose gateway placement (local Docker or remote server).
4. **Model provider** — connect Anthropic, OpenAI, or Ollama with a BYO API key.
5. **First agent** — create an agent from the recommended template and optionally connect a messaging channel.
After the wizard, a **Mission Panel** tracks progressive onboarding (assign a task, add knowledge, create a second agent, etc.) and auto-dismisses when complete. See [Workspace setup](/guides/workspace-setup) for full details.
## Dashboard
The dashboard is the operating view for the workspace. It summarizes:
* Agent fleet health.
* Gateway status.
* Open tasks and streams.
* Recent activity.
* Notifications.
* Fleet usage and budget status.
The dashboard is backed by Supabase realtime subscriptions, so most operational changes appear without a full refresh.
## Agents
An HQ agent is a long-lived workspace — not a chat wrapper.
Identity files, memory, skills, and artifacts on a dedicated branch.
Persistent cookies, logged-in sessions, and extensions.
Telegram, Discord, Slack, or none. Each agent gets its own channel binding.
Per-agent model and reasoning depth. Override per-task for one-off complex work.
Optional manager/direct-report relationships for delegation.
Optional monthly limits with soft warnings and hard cutoffs.
Agents are created from templates under `templates/`. The creation wizard lets you choose a template, set identity fields, select a manager, choose a messaging channel, enter credentials, and watch the gateway provisioning command run.
The agent detail page includes:
* **Overview** — status, capabilities, knowledge items, skills, direct reports, and routines.
* **Secrets** — credentials and keys this agent can use, with inherited gateway secrets and per-agent overrides.
* **Files** — file browser/editor for the agent's git branch.
* **Browser** — remote desktop access through the assigned gateway.
* **Activity** — usage summary, inbox history, and command/operation history.
* **Model and thinking level** — pick any connected model and reasoning depth from the right rail. Changes take effect on the next wake, no restart needed.
## Agent Templates
Templates are role-specific starting points for agents. The repository ships 16 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, and social writer.
Each template includes files such as:
* `agent.json` for runtime metadata.
* `IDENTITY.md` for role, voice, and domain behavior.
* `SOUL.md` for goals and non-negotiables.
* `USER.md` for owner profile placeholders.
* `MEMORY.md` and `memory/` for persistent context.
* `TOOLS.md` for tool-use guidance.
* `skills/` for repeatable procedures and scripts.
When the gateway boots for the first time, it seeds each template into the local bare repo as a `template/` branch. Provisioning an agent creates a new branch from the selected template and commits the personalized files.
## Agent Files and Memory
Agent source of truth is the gateway worktree. Agents can update their own files during work, and the operator can edit files from the UI.
The file browser talks to the gateway files API. Every create, edit, or delete is committed to git, then the UI enqueues an update command so the gateway reloads the agent.
Typical memory files:
* `MEMORY.md` for curated long-term memory.
* `memory/YYYY-MM-DD.md` for daily notes.
* `history/` files for longer work narratives.
* Skills under `skills/` for reusable procedures.
Optional git remote sync can push commits to GitHub or another git host for backup.
## Agent Organization and Delegation
Agents can report to other agents through `agents.reports_to_id`. The UI prevents self-reporting and cycle creation.
The agents list has a Fleet / Org chart view toggle that appears once at least one agent has a manager. The chart renders the reporting tree as connected boxes with collapsible subtrees. On each agent's detail page, the sidebar shows an "Org" section with the agent's manager, peers, and direct reports — the manager pill opens a picker for inline reassignment.
Runtime boot context includes:
* The agent's manager.
* The agent's direct reports.
* Delegation rules.
The intended operating model is:
* Delegate to direct reports by assigning tasks.
* Escalate to a manager by creating a high-priority task.
* Ask the human before routing work to peers outside the direct hierarchy.
## Usage Tracking and Budgets
HQ records LLM usage in `agent_usage` and rolls it up into `agent_budgets`.
The budget system tracks:
* Provider and model.
* Input, output, cache-read, and cache-write tokens.
* Estimated cost when pricing is known.
* Current monthly spend.
* Metered and unmetered calls.
* Soft threshold warnings.
* Hard cutoff status.
Budgets can be configured per agent. When a hard cutoff is enabled and an agent exceeds its monthly limit, the runtime blocks further replies and the inbox dispatcher stops waking that agent for background work. Budget transitions also create notifications.
## Secrets Management
Agents need credentials — API keys, OAuth tokens, webhook secrets — to interact with external services. HQ provides a unified encrypted secrets system that stores, syncs, and injects these values securely.
AES-256-GCM encryption. Values are never visible after saving — not in the UI, API responses, logs, or LLM context.
Secrets propagate to the gateway within seconds via Supabase Realtime. The sync status is visible in the UI.
Gateway-wide or per-agent. Agent-scoped secrets override gateway defaults automatically.
**Settings → Secrets** manages workspace-level credentials available to all agents. The **agent detail → Secrets tab** shows per-agent overrides and inherited gateway secrets.
Three categories:
* **User** — manually added API keys and credentials (e.g. `SALESFORCE_API_KEY`).
* **Channel** — auto-created when an agent is provisioned with a messaging channel (e.g. `TELEGRAM_BOT_TOKEN`).
* **Integration** — auto-created by OAuth flows (e.g. Notion access tokens for source sync).
Secrets are delivered to agents as environment variables via per-agent `.env` files on the gateway filesystem. Agent tools read them with `os.environ.get("SECRET_KEY")`. The AI model never sees secret values — only the tools it runs can access them.
For details on encryption, key derivation, and the sync protocol, see [Secrets management](/guides/secrets-management).
## CRM
The CRM stores people, organizations, interactions, campaigns, message templates, and draft sets.
Core capabilities include:
* Contacts and organizations.
* Contact-organization relationships.
* Interaction timeline.
* Dynamic custom fields.
* Pipeline stages and kanban views.
* Import wizard with mapping and duplicate handling.
* Campaign and draft workflows.
* Routine triggers that can assign work to agents.
CRM records are regular Supabase rows. Agents can read and update them through the bundled HQ skills.
## Tasks
Tasks are the main coordination primitive between the human and agents.
Tasks support:
* Human, agent, or system assignees.
* Streams for grouping work.
* Statuses such as todo, in progress, blocked, done, cancelled, and missed.
* Priorities and due dates.
* Recurrence rules.
* **Subtasks** — tasks support one-level nesting via `parent_id`. Create subtasks inline from the task detail panel. Parent tasks display a progress chip (done/total) in both list and board views, with a progress bar in the detail panel. Subtask status can be toggled directly from the subtask list. Subtasks inherit the parent's stream and show a breadcrumb link back to the parent task.
* **Per-task model and thinking overrides** — when assigned to an agent, override the model or reasoning depth for this specific execution without changing the agent's default.
* **Relations and dependencies** — link tasks with `blocked_by`, `blocks`, `relates_to`, `parent_of`, and `child_of` relationships. Blockers are highlighted in the task list and task form. When a blocking task completes, a `notify_blocker_resolved` trigger creates an inbox item for the unblocked task's assignee.
* **Labels** — managed workspace labels with configurable colors. Labels can be created from Settings → Labels or inline from the task form. Tasks display label pills in list and board views, and a label filter is available in the toolbar.
* **Deliverables** — agents submit work products (pages, URLs, or collection records) to tasks for human review. The review workflow supports approve, request revision (with note), and reject actions. Deliverables appear in the task form's Deliverables tab.
* **Task templates** — reusable task group templates with dependency graphs. Create templates from Settings → Templates, then spawn them from the task toolbar. Dependencies between template items are preserved as `blocked_by` relations on the created tasks.
* **Overdue escalation** — a pg\_cron job marks tasks past their due date as `missed` and creates inbox items to notify assigned agents. The task form shows a missed-task banner with a reopen action.
* Comments and mentions.
* Entity links to knowledge items, contacts, organizations, collection records, and URLs.
* Agent inbox wakeups on assignment and reassignment.
* **Agent delegation** — agents can delegate subtasks to direct reports via `hq_delegate_task.py`, which validates the org-chart relationship, creates a subtask with `child_of` relation, and inherits the parent task's stream.
Mentioning an agent in a comment creates an inbox item for that agent. Assigning a task to an agent does the same. Per-task model overrides are carried through the inbox item's context and passed to the agent session at wake time. The inbox dispatcher enriches task assignment items with unresolved blocker information so agents know what dependencies exist before starting work.
## Knowledge
The knowledge system is the unified store for all workspace knowledge. It replaces the earlier separate documents and assets models with a single `knowledge_items` table supporting four kinds:
* **Pages** — rich-text documents (company briefs, style guides, meeting notes).
* **Skills** — structured procedures and SOPs.
* **Files** — uploaded files (PDFs, images, spreadsheets, audio, video).
* **Sources** — externally synced content from connected integrations via the plugin-based source connector system.
Knowledge items support folders, tags, rich editing, and semantic + full-text search.
Source connectors are self-contained plugins — each provider is a folder under `gateway/connectors//` with a `manifest.json` that declares auth, UI metadata, and capabilities. The platform handles credential encryption, OAuth flows, UI forms, sync scheduling, and embedding automatically. Providers that support it can enable two-way sync with a `writable` toggle per connection. See [Knowledge system — Source connectors](/concepts/knowledge#source-connectors) for the architecture.
Agent boot context is controlled by **scope**:
* A **library-scoped** item is shared workspace-wide context, included in every agent's startup context.
* A **workspace-scoped** item lives in the workspace knowledge base but is not automatically injected into agent context.
* An **agent-scoped** item assigned to specific agents is included only for those agents.
See [Knowledge system](/concepts/knowledge) for the full architecture and [Knowledge and agent context](/guides/agent-boot-docs) for the practical guide.
## Routines and Inbox
Routines convert workspace events and schedules into agent work. Each routine has a trigger (event-based or schedule-based) and an assigned agent.
Supported event triggers include:
* Contact created.
* Contact status changed.
* Contact fields updated.
* Task assigned or reassigned.
* Agent mentioned in a comment.
Schedule triggers run on a cron schedule (e.g. every 15 minutes, hourly, daily) and wake the assigned agent at each interval.
Routines create `agent_inbox_items`. The gateway dispatcher leases pending inbox items, checks whether the target agent belongs to that gateway, verifies budget status, and wakes the agent through OpenClaw.
Inbox items have retry state, attempt counts, lease fields, done/failed/dead-letter statuses, and deduplication keys.
## Gateways
A gateway is a Docker host that runs agents. One workspace can have multiple gateways.
The gateway stack includes seven services (all behind the `gateway` Compose profile):
* **Gateway** container with OpenClaw, Chrome/Chromium, XFCE, noVNC, and the files API.
* **Dispatcher** daemon for agent inbox work.
* **Runner** daemon for lifecycle and operations commands.
* **Embedder** daemon for knowledge indexing and vector search.
* **File processor** daemon for extracting text from uploaded files (PDF, DOCX, XLSX, etc.).
* **Plugin runner** daemon for dispatching workspace events to local and webhook plugins.
* A shared `gateway-state` volume for OpenClaw config, git repo, worktrees, browser profiles, desktop files, plugins, and auth state.
The Settings -> Gateways UI supports:
* Viewing gateway status and stale heartbeats.
* Adding a gateway with a single-use registration token.
* Generating a `curl | bash` installer command for a remote host.
* Removing gateways.
* Editing labels and reachable URL overrides.
* Opening the noVNC desktop modal.
## Gateway Backup and Restore
Gateway state — auth tokens, agent configurations, secrets, and messaging channel pairing (e.g. Telegram) — is automatically backed up to Supabase Storage on shutdown and restored on fresh boot. This means a gateway can be destroyed and recreated without losing its operational state.
Backups are managed from **Settings → Backups**, where you can view existing backups, trigger a manual backup, or restore from a previous snapshot.
## Provider Connections and Models
HQ is model-agnostic. Agents work with whatever provider you connect — there is no required or default provider.
OpenAI, Anthropic, Gemini, DeepSeek, Mistral, MiniMax, and more.
OpenAI subscription, GitHub Copilot, and interactive flows.
Ollama, LM Studio, vLLM, and OpenAI-compatible servers.
Model provider auth is managed from Settings → Connections and from the agent rail. The command runner handles auth flows through `agent_commands`.
When the same models are available through multiple connections (e.g. OpenAI API key and OpenAI subscription), HQ unifies them into a single provider group. If both are connected, models appear with route labels ("Subscription" / "API") so you can choose which billing path to use. Subscription-only models like Codex Mini only appear when that connection is active.
## Model Selection
Every agent can run a different model and thinking level — no gateway restart needed, no global config change. This is a core design choice: a fleet of agents should be able to mix expensive reasoning models for complex work with fast cheap models for simple lookups.
Set from the agent detail sidebar. Persists across sessions. The agent always wakes with this model unless a task override says otherwise.
Override the thinking level (or model) for a specific task. Useful for one-off complex reasoning without changing an agent's default. Passed at wake time through the inbox dispatch mechanism.
### How it works
| Layer | What it controls | Set from |
| --------------------- | ------------------------------------------------------------- | ------------------------------------------------------ |
| **Workspace default** | Fallback when no agent-level or task-level override exists | Settings → Connections (first connected model) |
| **Agent default** | The model and thinking level this agent uses by default | Agent detail page → Model section (right rail) |
| **Task override** | Overrides the agent's default for one specific task execution | Task form → Model override (when assigned to an agent) |
Resolution is bottom-up: task override wins over agent default, which wins over workspace default.
### Thinking levels
For models that support extended reasoning (Claude, o-series), HQ exposes a thinking level selector:
| Level | Behavior |
| ---------- | ---------------------------------------------------------- |
| **None** | No extended thinking — fastest and cheapest |
| **Low** | Brief internal reasoning |
| **Medium** | Moderate reasoning depth |
| **High** | Maximum reasoning depth — most capable, highest token cost |
### Multi-route providers
Some providers serve the same models through different billing paths. OpenAI models (GPT-4.1, o3, o4-mini) are available both via API key (pay-per-token) and via ChatGPT subscription (included in your plan). HQ handles this transparently:
* **One connection:** Models appear under "OpenAI" with no qualifier.
* **Both connections:** Each model appears twice with "Subscription" (preferred) and "API" route labels. Choose which billing path each agent uses.
* **Exclusive models:** Codex Mini is subscription-only and only appears when that connection is active.
See [Connect a model provider](/guides/connect-model-provider) for setup and [Inbox dispatch](/reference/inbox-dispatch) for how overrides reach the agent runtime.
## Networking
HQ's default networking model is host-controlled:
* Local mode binds services to loopback.
* Tailscale mode installs or uses Tailscale on the host, not inside containers.
* Public mode expects a host-level reverse proxy or tunnel.
Gateways register their reachable URLs in Supabase so the UI can open the correct files API and noVNC endpoint for each gateway.
## Notifications and Activity
HQ records important workspace events in `notifications`, `audit_log`, command history, inbox history, and activity feeds. Examples include:
* Budget warnings and exceedances.
* Command completion or failure.
* Agent lifecycle actions.
* Task and CRM events.
* Gateway state changes.
This gives the operator a single place to understand what happened and why.
## Plugins
HQ has a built-in plugin system for reacting to workspace events. Plugins can send Slack notifications when tasks complete, sync data to Linear, trigger webhooks for Zapier, log budget alerts, or run any custom logic.
Python modules on the gateway with full SDK access — state persistence, secret resolution, and Supabase queries. Best for logic that needs to read HQ data.
Remote HTTP endpoints. Zero gateway code — HQ POSTs events with HMAC signatures. Best for connecting to external services and no-code tools.
16 built-in events cover tasks, agents, knowledge, inbox, routines, comments, secrets, usage, and budgets. The plugin runner daemon dispatches events to all matching plugins in real time.
Manage plugins from **Settings → Plugins** — enable/disable, configure, view event logs, and add new webhook plugins from the UI. See [Plugins](/concepts/plugins) for the full architecture and [Plugin events](/reference/plugin-events) for the event reference.
## Extensibility
Most customization does not require changing code:
* Add templates under `templates/`.
* Add skills to templates.
* Configure fields, pipeline stages, streams, and routines in the UI.
* Add model providers through connections.
* Add gateways through Settings.
* Add webhook plugins from Settings → Plugins (no code needed).
Code extension points include:
* New UI pages under `apps/ui/src/app`.
* New gateway command actions in `gateway/daemons/command_runner.py`.
* New routine behavior in database functions/triggers.
* New agent skills under template `skills/`.
* New OpenClaw plugins in `gateway/scripts/plugins/`.
* New source connectors under `gateway/connectors//` — copy the `_template/` directory and implement the connector interface. See `CONTRIBUTING-SOURCES.md`.
* New HQ plugins under `gateway/plugins//` — copy `_template/`, implement `on_event()`, and subscribe to events. See [`gateway/plugins/CONTRIBUTING.md`](https://github.com/yourhq/yourhq/blob/main/gateway/plugins/CONTRIBUTING.md).