Queen architecture

The technical picture of Queen for builders and auditors: the two-plane model, the application split, identity and signed commands, and the hard data boundary. Queen is in active design; the architecture is decided across its decision records. Grounded in the Queen technical manual.

Queen architecture

Related:

#Overview

Queen is the control plane for a multi-machine Apiary fleet. It sits beside the data plane, never inside it. The data plane is the existing Deep Lake dataset that carries memory, sessions, and skills, unchanged. The control plane is Queen, carrying liveness, status, identity, enrollment, signed commands, coarse usage facts, and ROI.

#Two applications

The local Queen agent. A command-line-only Node application, packaged as @legioncodeinc/queen, that runs on every machine. It has no local dashboard and no human-facing HTTP listener. It binds to a cloud deployment as a required boot step, reports presence and coarse usage facts, redeems enrollment tokens, holds per-agent identity, and polls the signed command channel. It is inert until it is bound.
The cloud Queen application. A backend and a server-rendered frontend that serve every dashboard and the control-plane API, from the hosted deployment or a customer's own licensed deployment. It owns the database boundary, ingestion, auth, and licensing.

#The four-role topology it joins

Honeycomb is the memory engine, reading and writing the dataset every turn; Queen observes its liveness, never its memory content. Nectar is the understanding and skill layer; Queen observes it, and skills stay on the data plane. Doctor is the local watchdog and telemetry source of truth; Queen's presence view is fed by and complementary to Doctor's local telemetry, adding the cross-machine view Doctor cannot render alone. Hive is the local portal on 127.0.0.1:3853, which stays local; Queen adds the fleet views no single machine can render.

#Presence and the heartbeat

Liveness is derived, never guessed. Each daemon writes a cheap last-seen heartbeat on a fixed interval, plus a richer status record only when something changes. A daemon is live when its last heartbeat is recent enough. Stale entries are reaped so dead throwaway agents never pile up, and a presence error never blocks real work.

#Identity and signed commands

Every agent, including throwaway sub-agents, gets its own attributable, revocable identity. Per-agent keypairs are generated locally; the private key never leaves the machine, and the control plane stores public keys only. One authority signs every command, and workers verify against a pinned public key. Command delivery is pull-based, idempotent, and acknowledged, built to survive a flaky transport. If the authority is down, workers degrade to autonomous rather than failing. Enrollment tokens are short-lived and single-use, and only their hash is stored, never the secret.

#The hard boundary

The database holds coordination state and coarse usage facts only: never memory content, prompts, completions, session text, tool-call payloads, file paths, repo names, or plaintext credentials. Where a credential must be referenced, only ciphertext and wrapped-key metadata are stored, and the cloud cannot decrypt it in the default mode. Presence never writes into the memory dataset, and idle daemons never poll the dataset for coordination work.

#Auth, tenancy, and ROI

Human sign-in uses an external identity provider with an org, workspace, and team model. Every control-plane route is org-scoped, and tenancy is enforced on every request. Cross-org ROI reads are fenced behind an explicit entitlement, separate from org membership, and per-user views stay inert until identity is verified. The usage ledger is append-only, and every row carries whether its cost is measured or allocated; the aggregation read never silently blends the two.

#Observation boundary in the first version

The usage observer captures coarse facts only, the model identifier, token counts, timestamps, agent identity, harness, and cost basis, from command-line and model-gateway traffic. Desktop interception is explicitly out of scope in the first version: no certificate authority, no interception on enrolled machines. No prompts, completions, or session text cross the boundary.

#Licensing

Released under the GNU Affero General Public License, version 3.0 or later. The license check is fused into the cloud binding handshake rather than a separable gate: the handshake validates the license and issues the runtime material, so no binding material means no running agent. It fails closed and degrades loud, with a bounded grace window for a transient authority outage only.