How queen works

queen is coming soon; this page describes the design, not a shipped product. It's written for people who want the mechanics before they trust a fleet to it: how presence gets tracked, how identity works, how commands travel, how ROI gets measured, and where the hard line sits between what queen coordinates and what it will never touch.

#How will queen know which agents are alive?

Liveness is derived, never guessed. Each daemon writes a cheap "I'm still here" heartbeat on a fixed interval, and a fuller status record only when something actually changes, so the system isn't flooding itself with redundant writes. An agent counts as live when its last heartbeat is recent enough, and stale entries get reaped automatically so dead throwaway agents never pile up on the dashboard. A presence hiccup never blocks real work; the worst case is a dashboard that's a little behind, not an agent that stalls.

That feed becomes a read-only fleet dashboard, scoped so you only ever see your own org's fleet. It sits alongside doctor, which stays your local watchdog and telemetry source of truth. queen's presence view doesn't replace doctor, it adds the cross-machine view no single machine's doctor can render on its own.

#How does per-agent identity and enrollment work?

Every agent gets its own identity, and that includes throwaway sub-agents that spin up and vanish in minutes. Each one generates its own keypair locally; the private key never leaves the machine it was created on, and the control plane only ever stores the public half. That matters because it means there's no shared forever-key anywhere in the system. If one agent's identity is compromised, you revoke that one identity, and the rest of the fleet is untouched.

Adding a new machine works through a short-lived, single-use join token. An already-trusted machine mints the token, the new machine redeems it, and only the token's hash is stored, never the secret itself. No browser has to open on the server, no credential gets pasted into a config file, and nothing is shared between machines beyond that one narrow, expiring token.

#How do signed commands travel, and what happens if the authority is down?

One authority signs every command, and agents verify that signature against a pinned public key before acting on anything. Delivery is pull-based: agents poll for commands rather than having them pushed in, which makes the whole channel idempotent and able to survive a flaky connection without duplicating work.

If the signing authority goes down, agents don't stop. They keep doing their local work and keep sending heartbeats; they just can't pick up new commands until the authority is back. That's a deliberate design choice: a control-plane outage degrades the fleet to autonomous, never to dead.

#How does hosted ROI reporting work?

queen will roll up spend and usage per org, per team, and per user, from a shared, append-only usage ledger. Every row in that ledger carries whether its cost is measured or allocated, and the two are never quietly blended together in a report, so a number you see is honest about how it was derived.

In the first version, the usage observer reads coarse facts, model identifier, token counts, timestamps, agent identity, harness, and cost basis, off command-line and model-gateway traffic. It does not intercept desktop apps: no certificate authority gets installed on your machines, and no one is decrypting your desktop traffic to build this picture. That's an explicit, deliberate boundary, not an oversight, because a root CA on every enrolled machine is exactly the kind of capability queen is built to avoid needing.

Per-user views stay inert until a verified identity exists behind them, so there's no self-asserted name showing up on a leaderboard, and per-user spend is treated as personal data with its own visibility controls.

#What is the orchestrator-custodian model, and why does it matter?

This is the core trust decision behind queen. Your memory lives in Deeplake, and something has to hold the credential that unlocks it. queen's answer is that a durable machine inside your own trust domain, your long-lived orchestrator, holds that credential, not the cloud.

The orchestrator links Deeplake once, keeps its own private custodian key locally, and encrypts the credential before anything about it ever reaches queen's cloud. From there, throwaway workers get memory access in one of two ways: brokered, where a worker never sees the credential at all and just asks the orchestrator to do memory operations on its behalf, or issued-access, where a worker gets a short-lived, narrowly scoped credential rewrapped just for it, good only for a limited time. Either way, ephemeral workers never hold a long-lived key, so a worker VM that gets torn down after ten minutes was never a place your credential could leak from.

queen's cloud side owns fleet records, presence, enrollment validation, and encrypted blob storage, full stop. It cannot decrypt the credential blob in the default mode. If the only orchestrator holding that key is lost, queen cannot recover it either; you'd re-link Deeplake or restore the orchestrator's key from your own backup. That tradeoff is the whole point: the promise "we cannot read this" only means something if it's also true when it's inconvenient.

#The hard boundary

This is the line queen is built never to cross. The control plane holds coordination state and coarse usage facts only, meaning liveness, identity, enrollment records, signed-command metadata, and the usage ledger. It never holds memory content, prompts, completions, session text, tool-call payloads, file paths, repo names, or plaintext credentials. Where a credential has to be referenced at all, only ciphertext and wrapped-key metadata are stored, and the cloud cannot decrypt it by default. Presence tracking never writes into the memory dataset, and an idle daemon never polls the memory dataset just to coordinate.

#Common questions

How will queen know which agents are alive? Each daemon writes a cheap heartbeat on a fixed interval, plus a fuller status update when something changes. queen derives liveness from how recent the last heartbeat is, and reaps stale entries so dead throwaway agents don't pile up.

What is per-agent identity, and why does every agent get one? Every agent, including a sub-agent that only lives for a few minutes, gets its own keypair and its own revocable identity. There is no shared forever-key, so revoking one agent cuts off exactly that one, not the whole fleet.

What happens to commands if the signing authority goes down? Agents keep doing local work and keep reporting in. They just can't receive new commands until the authority is back. queen is built so a control-plane outage degrades agents to autonomous, never to dead.

Who actually holds the key to our memory? Your own long-lived orchestrator, not the cloud. queen's orchestrator-custodian model keeps the Deeplake credential on a machine inside your trust domain, and the control plane only ever sees encrypted blobs it cannot open.