Skip to content

Turn on Facet

Facet is the assistant behind the Facet button on every page of Hivemind. It answers from your instance, proposes work as cards, and, with the Commander link, carries a question to your Commander and brings the answer back into the same conversation.

Facet is created on the first start of the server, already enabled. What it needs from you is a model provider and that provider's key. Until it has a key, Facet refuses each message with the reason and the setting to fix, and reads nothing.

1. Choose the provider

One setting in your install's .env chooses the provider that serves Facet:

HIVEMIND_ASSISTANT_PROVIDER=anthropic
Value Facet runs on Key it reads Model a new install gets
anthropic (what install.sh writes) Anthropic the same key as your agents' provider: HIVEMIND_LLM_API_KEY_FILE, else HIVEMIND_LLM_API_KEY (see Bring your own LLM) claude-sonnet-4-6
openai OpenAI, or an OpenAI-compatible server its own key: HIVEMIND_OPENAI_API_KEY_FILE, else HIVEMIND_OPENAI_API_KEY, else OPENAI_API_KEY gpt-6-sol

This setting is separate from HIVEMIND_LLM_PROVIDER, which chooses the provider for agents and other LLM features. The two can differ. For example, agents can run on Anthropic while Facet runs on OpenAI, and each keeps its own key.

If you change the provider later, restart the server. A model you never edited moves to the new provider's model on that restart. A model you chose yourself is kept. Choose a different model on the Assistant profile (Bots page), or in the chat's model picker.

For the OpenAI provider, two more settings are optional:

  • HIVEMIND_OPENAI_ENDPOINT: an OpenAI-compatible server instead of OpenAI's own.
  • HIVEMIND_OPENAI_API=chat: keep OpenAI's own endpoint on the chat completions API. A custom endpoint always uses chat completions.

2. Give it the key

The simple way: a setting in .env

For Anthropic, set HIVEMIND_LLM_API_KEY in .env, as Install describes. For OpenAI:

HIVEMIND_ASSISTANT_PROVIDER=openai
HIVEMIND_OPENAI_API_KEY=<your key>

A key in .env reaches the server as an environment variable. Anyone who can run docker inspect on the server container can read it.

The safer way: a key file

The _FILE settings take a path inside the server container, so the file must be mounted into it. Keep the file outside secrets/: install.sh locks any file in secrets/ that it does not know to your own account, and the server would then be unable to read it.

  1. Put the key in a file the server can read. The server runs as user hivemind, uid 1000; sudo docker compose exec -T server id -u confirms it on your install.

    mkdir -p assistant-key
install -m 600 /dev/null assistant-key/openai_api_key
# write the key into that file with your editor; never on a command line
sudo chown 1000 assistant-key/openai_api_key

  2. Mount it, in docker-compose.override.yml in your install directory. Managed updates change only the image digests in this file and keep everything else. Merge these lines into the file; do not replace it:

    services:
  server:
    volumes:
      - ./assistant-key/openai_api_key:/run/assistant-key/openai_api_key:ro

  3. Point the setting at the path inside the container, in .env:

    HIVEMIND_ASSISTANT_PROVIDER=openai
HIVEMIND_OPENAI_API_KEY_FILE=/run/assistant-key/openai_api_key

    For Anthropic, mount the file the same way and set HIVEMIND_LLM_API_KEY_FILE instead.

A key file that is configured but cannot be read, or is empty, fails closed. Facet refuses; it does not fall back to a key in .env. Remove the _FILE setting to go back to the plain one.

3. Apply

sudo docker compose up -d server

Compose recreates the server only if its settings changed.

4. Check it

Sign in, open Facet from any page and ask something about your instance, such as "what is running?". Facet answers.

If the key is missing, Facet refuses with the reason and the setting to fix. For example: "no OpenAI API key is configured on this installation, so nothing was asked and nothing was read", and it names the setting to set. For a key file, also check the server's log (sudo docker compose logs server). It says whether the file was configured and could not be read.

Who can do what in Facet

  • Every signed-in person can talk to Facet. Each person sees answers limited to what their role may read (Role capabilities).
  • Without administrator rights, a person can still have Facet propose a few things of their own: watch a URL, stop one of their monitors, send a message to an agent they started, or file a work item where your instance allows it.
  • Only an administrator can ask the Commander a question, or start, message or stop any other agent through Facet.
  • Every proposal is a card, and nothing happens until it is confirmed, once, in a signed-in browser. An API key cannot confirm a card.

Next