Skip to content

What happens when you ask it something

If you have seen Hivemind demonstrated, this is the sequence you watched, in order and in plain terms.

Status: steps 1 to 4 run on every install; step 5 needs the agent runner

Steps 1 through 4 (asking, the live reading, the proposal, and your confirmation) are what every installation does, once Facet has a model key (Turn on Facet). Step 5 needs the agent runner, which a standard install does not start. The runner ships in docker-compose.yml behind an opt-in runner profile, and it needs four things. Install lists all four, with a check for each:

  • its own API key, which install.sh mints for you;
  • the Anthropic key for agents, which you supply as a file: --claude-api-key-file <path>, or secrets/claude_api_key placed before installing. The invite path does not prompt for it;
  • a digest-pinned runner image reference, which comes with your bundle;
  • a git repository on your host for agents to work in, named by HIVEMIND_RUNNER_REPO_PATH in .env.

Configuring an LLM provider does not substitute: a provider key enables the LLM-backed surfaces, not agent execution.

Approval of a queued escalation also does not yet dispatch. An approved escalation is not consumed by an executor, so the approve-and-resume leg does not complete on its own. Confirming a proposal in Facet, under your own signed-in session, is the path that causes work today. See Approval-escalation path.

The rest of this site documents each of these steps in depth, from the inside. This page is the door; those are the rooms, and each step links down to its own.

1. You ask, in a conversation

You type a question or a request in ordinary language — no command syntax, no console. You are talking to Facet, the conversational surface, and you are signed in as yourself.

Who you are is carried into everything that follows. Two colleagues on the same installation can ask an identical question and get different answers — each scoped to what that person is permitted to see. The same applies to what each of them can propose: an assistant belonging to someone without the authority to dispatch work is told so plainly, rather than quietly losing the ability.

2. It looks, rather than remembers

This is the part that surprises people, and it is deliberate.

Asked about the state of your systems, it does not answer from documentation. It goes and takes a reading. The answer comes back with a timestamp, because it is a measurement made just then rather than something recalled.

If there is no live check registered for the thing you named, it tells you exactly that — and tells you what would fix it. It does not quietly answer from a document instead, and it does not substitute a different measurement that happens to be available. A near-miss answer to the question you asked is worse than no answer, because you cannot tell the difference from the outside.

The cost of that is real: sometimes you get "I can't check that" instead of a confident paragraph. The benefit is that when it does answer, the answer is a reading, and it says when it was taken.

3. If someone has to go and look, it proposes

Some questions cannot be answered by a reading. They need work — investigating a service, gathering something that is not already exposed.

At that point the assistant writes a proposal and hands it to you, along with the proposal's id so it can be pointed at afterwards.

It cannot carry the proposal out. This is not a policy it has been asked to observe; there is no path from the model to running work. The surface it holds has no verb that executes. It can describe what it would do and ask you for it, and that is the end of what it can do on its own.

How that boundary is built, and what happens to an action that needs a human: The approval-escalation path · Per-target capability authz

4. You confirm — and that is the only thing that starts work

You look at the proposal and confirm it.

Your confirmation is the only thing in the product that causes work to start. The model cannot produce it and cannot reach the place it happens. That is the whole design in one sentence: the thing that reasons is not the thing with authority.

The control disappears once you have used it. You cannot confirm the same proposal twice, by accident or otherwise.

The security properties this rests on: Security mechanisms · The unified per-target gate

5. An agent runs, and reports back

With the agent runner enabled, an agent starts, does the work, and reports its result back into the same conversation. You do not refresh anything or go looking for it: while the agent runs, a live strip shows it in the conversation, and when it finishes its result arrives there as a card. You can ask Facet "what are my agents doing?", send an agent a message, or stop it. Each message and each stop is a card you confirm.

Without the runner, this step does not happen, and nothing announces that. The API and the web UI do not report whether a runner is present, so check the runner container itself, as Install shows.

What the agent is and how it is driven: How it connects · The remote-Commander control channel

Two things worth being precise about

Where the agent runs

Where a runner is present, the agent runs on the machine Hivemind is installed on — not on a separate fleet of remote targets. That is the current design, and it is what you should assume when reading anything on this site about targets and boxes. The runner is an opt-in part of the install; see the status note at the top of this page.

Routing work across an estate — choosing the machine a given target actually lives on, and running the work there — is the direction this is going. It is not what runs today.

Confirming a proposal is not the same as approving a queued escalation

These are two different mechanisms, and it matters because one of them is finished and the other is not.

  • Confirming a proposal is the flow described on this page. It works, and it is what you saw demonstrated.
  • Approving a queued escalation is a separate path, for an action that was attempted, refused, and raised for a decision. The decision is recorded correctly — but an approved request is not yet picked up and run. That page says so.

If you read the caveat there and concluded that the sequence on this page does not work either, that is the confusion this section exists to remove. They are different paths and only the second one is unfinished.

Where to go next