One binary. One folder of markdown.

02

Crate map

The workspace is Rust edition 2024 with 24 crates and about 289,000 lines of Rust. Foundations hold types, storage and the LLM clients. The agent crate holds the session loop, sub-agents, governance and the context engine. Services wrap those for a transport, and hq-backup writes and restores encrypted backups of the vault and its database. hq-host and hq-sandbox run and confine coding agents, and hq-gate is the signed TCP transport for the host gate over a private tunnel.

Four crates connect devices. hq-bridge pairs machines with a one-time QR code and reconnects them by key. hq-edge is a blind public forwarder that routes by TLS server name to a registered device. hq-net sets up a private WireGuard network, and hq-tunnel is a userspace WireGuard peer for a phone. hq-cli ties them into the binary, and hq-desktop holds the macOS desktop app's logic with no GUI dependency.

The stack, in short: Tokio for async, Axum and tower-http for the web server, rusqlite (bundled, WAL mode) for storage, rmcp for MCP, serenity for Discord, teloxide for Telegram, clap for the CLI and figment for configuration. LLM calls go through async-openai with a swappable base URL, which is how OpenRouter, Ollama and other OpenAI-compatible backends plug in. A direct Anthropic Messages client sits beside it, with prompt caching. Every call is priced in one place, and spend shows on the /usage page.

04

The daemon and its scheduled tasks

The daemon is a plain interval scheduler. It ticks every 5 seconds and runs whichever tasks are due, one after another, each with a timeout derived from its interval tier. A missed task is detected on the next start. After every tick it writes DAEMON-STATUS.md at the vault root, so you can read what ran with cat.

The fast tier handles approvals, harness-session supervision, the heartbeat, value-bus delivery and the email poll. The memory tier handles consolidation, embeddings, note tagging and forgetting. The maintenance tier handles vault health, thread rotation, clean-up, a disk watchdog and SQLite vacuum. Beside the scheduler, an agent worker triages inbound events and email, and a machine profile records which CLIs the host has.

Recurring prompts are not daemon tasks. They are /watch rows, covered with the relays below.

06

The web PWA

The Control Center is a React 19 app on TanStack Start and Vite, built to a static single-page bundle. hq start all serves it from :5678 along with the REST API and the chat socket, from web/dist next to the vault or the directory in web_static_dir. There is no separate web server process.

It streams the agent live, browses and searches the vault, shows daemon status, runs the tasks views, lists and drives sessions, renders DOCX, XLSX and PDF, and takes push notifications. It installs on a phone like any PWA.

Auth in the browser

The server binds to 127.0.0.1 by default. With web_auth_token set, the token is accepted only as a Bearer header, never in a URL. A browser cannot set headers on a WebSocket, so the app asks POST /api/ws-ticket for a ticket that works once, lasts 30 seconds and opens only /ws. An origin guard refuses requests from origins that are not loopback, not the server's own and not listed in web_allowed_origins, which also stops DNS rebinding. The response CSP has no unsafe-eval and no script unsafe-inline, and remote images are blocked on purpose, because an image URL is a way to send data out of a rendered note. Details: web and MCP auth.

08

The built-in host and supervised coding-agent sessions

HQ's built-in host (hq host) owns the terminals. It recognises which coding agent sits in a pane and reports its state: idle, working, blocked on a dialog, or done. HQ drives it over a local socket. Claude Code, Codex, Cursor, Pi, OpenCode, Copilot CLI, Kimi, Qwen and Antigravity are supported harnesses, and you can define your own profiles. This replaced an earlier tmux runner that could only guess state from screen text.

Personal agents

Hermes Agent and OpenClaw run in the same host as a second kind of harness, general-purpose agents. Every session has a purpose (research, review, monitor or general), and a request to give one code work is refused before anything starts. They get no HQ token and no MCP wiring: HQ types into them and reads their screen as untrusted text. Named in a stack: block, each pulls the tasks assigned to it and runs one as a single job, and the process ending puts the task into review. Setup and removal are in the personal agents guide.

Hosts

A host is a machine running hq host. native is the machine HQ runs on. Any other host is a machine you paired with hq host join and is reached over ssh with a dedicated key that is pinned to one source address and to a forced command, hq host gate, which accepts one request as JSON on stdin and refuses every method outside an allowlist. Agents run in a process sandbox. The default profile, open, walls off only HQ itself: the host's tokens, ~/.hq, other processes' environments, other agents' logins and, unless you turn it off, your credential stores. strict adds an egress allowlist and read and write allowlists. That is how HQ on a VPS can run and watch agents on a laptop, whenever the laptop is on and reachable. Connections are reused between calls, and a write is never retried because the gate may already have run it.

Spawning and watching

harness_session_spawn starts an agent and returns a session id. Send, wait, logs, status, stop and resume sit beside it, and hq sessions mirrors them in the CLI. A supervisor in the daemon polls every host once a minute. It alerts once when a session blocks and once when an agent finishes a turn. A host that cannot be reached counts as unknown, never as exited: a sleeping laptop leaves its sessions running and they are watched again when it answers.

HQ does not answer dialogs for you. Claude Code's workspace-trust prompt defaults to "No, exit", so pressing Enter would quit it. A blocked launch is reported with the screen, and you answer with explicit keys.

Sessions that work on a task

A session can be linked to a task. Each event leaves a task comment, and the task moves from in progress to ready for review or blocked as the session finishes or exits. By default HQ never marks a task complete, because an agent saying it is done is not verification. With task verification turned on (it is off by default), HQ completes a task only from evidence the agent could not have written, such as a merged pull request with green checks, and measures how often it is wrong. Comments never quote the pane, since pane text is untrusted input.

Handoff

harness_session_handoff lets an outside client, such as another agent over MCP, start tracked work in one call. It files or reuses a task by an idempotency key, starts one linked session with the acceptance criteria as its definition of done, and opens a chat thread that owns the session. It is idempotent: the same key returns the same task, and a task that already has a running session gets no second one.

Watching and driving from a web chat

A chat can watch a session. Watching posts short updates and never quotes the screen. Driving lets HQ act as the session's project manager: read the session, send the next instruction, approve a permission prompt or resume an exit, toward the linked task's goal. It asks you instead when a step is destructive, touches credentials, deploys or spends money. A new watch starts with Drive on only when the task gives it a usable goal, and observation-only otherwise. A turn that has read untrusted content starts new watches with Drive off, and a tool can never turn it back on once you switched it off. Mechanical limits cut it off without relying on the model: an instruction budget per session, a cap on key presses, a no-progress guard, and a cap on sessions driven at once. Each one switches Drive off and says why. The Sessions page shows every session with its task, host, goal and live state.

Full reference, including setup and troubleshooting: docs/AGENT_SESSIONS.md.

10

Governance and the bash sandbox

The agent's bash tool runs model-written shell commands, so HQ does not rely on the model refusing. A governance layer denies dangerous effects mechanically, before a tool runs, and it applies in permissive modes too.

Credential files such as ~/.ssh, cloud credentials and the HQ config are unreachable always. A session becomes tainted once a tool returns untrusted content: web fetch and search, mail, converted documents, other agents' mailboxes, session logs, pane reads, vault reads and any remote MCP result. Taint is shared with every sub-agent the session spawns, so delegating cannot launder it. After taint, project secrets such as .env files and outbound network from bash (curl, ssh, nc and similar) are denied.

For bash, three layers follow. Text checks catch honest mistakes and cheap tricks, but about 100 known obfuscation shapes are pinned in tests and some still get through, so they are speed bumps. An environment allowlist starts the child with an empty environment and a short list of variables. HQ's own keys are refused even if you list them. Then the OS sandbox: bubblewrap on Linux, sandbox-exec on macOS. On Linux it gives a read-only root, a fresh /proc in a new pid namespace, writable binds only for home, the working directory, temp and the vault, and optionally no network. Config, env files and private SSH keys are masked.

governance.bash.sandbox takes off, best_effort or required. After 0.9.0 the default is required: if no sandbox backend works, every bash command is refused and hq doctor says so.

What this does not cover is on the security page.

12

Deployment topologies

Laptop only. Run hq start all. The web server binds to loopback. Set web_auth_token on a shared machine. This is the default and needs no network setup.

VPS plus Tailscale. Provision a Debian or Ubuntu box with deploy/setup-vps.sh, install the signed updater with deploy/install.sh, and keep HQ on loopback. Caddy bridges to tailscale serve, which terminates HTTPS on your tailnet only, so the UI never touches the public internet. List every origin you serve the UI from in web_allowed_origins. HQ on the VPS can then drive the host on a laptop over the gated ssh key.

Docker. The image ghcr.io/calvinmagezi/hq is assembled from the same signed release artifacts as the install script, for linux/amd64 and linux/arm64, and runs as a non-root user with its state under /data. See docs/DOCKER.md.

Windows. Full HQ runs inside WSL2. On a computer that blocks WSL2, HQ Lite runs natively as one program with no administrator rights: the web app, tasks, notes and search, without coding agents, chat bots or the sandbox. See docs/WINDOWS.md and docs/HQ_LITE.md.

An Android phone (developer preview). The mobile profile is Full HQ for a machine with no shell sandbox, no git and no self-updater, plus a data saver. The APK is one you build yourself from apps/android. It is not yet verified that a sleeping, unplugged phone answers in time. See docs/HQ_MOBILE.md and apps/android/README.md.

A device behind NAT, with hq edge. A public forwarder you run yourself on a machine you control. It reads only the TLS server name, never decrypts, and passes the bytes to the registered device over an iroh stream. TLS ends on the device, which holds its own certificate. It is off by default and there is no project-run edge. See docs/EDGE.md.

A private network, with hq net. A WireGuard hub on a Linux server and your own devices as spokes, so the web UI, /mcp and the host gate are reachable only from devices you admitted. Release builds do not include the root applier yet, so that step builds it from source. See docs/PRIVATE_NETWORK.md.

Two shapes publish anything. A plain MCP endpoint goes through a proxy that exposes /mcp and /health and nothing else, with an API key set. The claude.ai connector publishes /mcp, /oauth/token, /oauth/revoke and the /.well-known/oauth-* metadata documents, and the consent page stays private (docs/CLAUDE_CONNECTOR.md, deploy/Caddyfile.connector). /ws and /api must never be public. A host runs one deploy path only: the pull updater, or a manual build, not both. Steps are on the install page and in deploy/README.md.