Skip to content

Hivemind — architecture overview

Hivemind is a self-hosted multi-agent orchestration platform. You install it once on your own infrastructure; it serves your users, talks to the LLM provider of your choice, and integrates with adjacent Seglamater products (Chatalot for E2E-encrypted chat, in the future Atlas + Vantage) on the same host or over a VPN. This document is the customer-facing overview: what the running pieces are, where data lives, and what's in scope for you to operate vs. what Seglamater operates on your behalf.

If you maintain Hivemind itself (Seglamater's engineering side), see internal-architecture.md for the homelab development testbed — that doc is excluded from the published site.

The one-paragraph picture

A Hivemind install is a small Docker Compose stack: a Rust API server, a Postgres database, and a tiny updater sidecar that periodically polls Seglamater for signed releases on your channel. Your users hit the server over HTTPS (terminated by your reverse proxy in front), the server talks to your LLM provider directly (BYOK — your key, your provider, your billing), and the updater pulls cosign-signed image digests when you click Apply in the admin Updates page. Seglamater never sees your data, your prompts, your agents' work, or your users' identities.

Components

                      ┌────────────────────────────────┐
                      │     Your users (browsers)      │
                      └────────────────┬───────────────┘
                                       │ HTTPS
                                       ▼
                      ┌────────────────────────────────┐
                      │   Your reverse proxy           │
                      │   (Caddy / Traefik / nginx)    │
                      └────────────────┬───────────────┘
                                       │ HTTP :8585
                                       ▼
   ┌───────────────────────────────────────────────────────────────┐
   │  Docker Compose stack (your host)                             │
   │                                                               │
   │  ┌─────────────────┐   ┌──────────────┐   ┌────────────────┐  │
   │  │ hivemind-server │──▶│ hivemind-db  │   │ hivemind-      │  │
   │  │ Rust / Axum     │   │ Postgres 17  │   │ updater        │  │
   │  │ :3000           │   │ :5432 (vol)  │   │ sidecar        │  │
   │  └────────┬────────┘   └──────────────┘   └────────┬───────┘  │
   │           │                                        │          │
   └───────────┼────────────────────────────────────────┼──────────┘
               │                                        │
               │ BYOK LLM (Anthropic / OpenAI /         │ poll signed
               │  Ollama / OpenAI-compat)               │ releases
               ▼                                        ▼
   ┌────────────────────────┐         ┌──────────────────────────────┐
   │ Your LLM provider      │         │ updates.seglamater.app /     │
   │ (your API key)         │         │ registry.seglamater.app      │
   └────────────────────────┘         └──────────────────────────────┘

hivemind-server — the Rust API + agent runtime

The load-bearing service. A single Rust + Axum binary that serves:

  • The public API (/api/v1/*) — agent profiles, chat, integrations, health, the public-tier chatbot endpoint.
  • The admin / operator API — auth (local accounts or SSO), agent spawn + lifecycle, cost tracking + audit, updates apply.
  • A WebSocket layer for live agent traffic + (when integrated) chatalot bot connections.
  • The agent runtime — the tool-call loop that drives an LLM through a task, with input sanitization, prompt-injection detection, PII scrubbing, and cost caps wrapping every call.

Binds 127.0.0.1:8585 by default. Your reverse proxy terminates TLS and forwards to it. The unauthenticated API surface (public chat, health) is intentionally narrow — admin / agent / integration routes require either a session cookie (browser) or X-API-Key (daemons).

hivemind-db — Postgres 17

Storage. One database, on a named Docker volume (hivemind_pgdata, not a host bind mount). Holds:

  • Local accounts (or, with SSO, just role bindings indexed by your IdP's subject claim).
  • Agent profiles (the personas + their tier / cost cap / rate limit).
  • Conversations, messages, audit log, cost-tracking rows.
  • Integration credentials — chatalot bot tokens, etc. — at rest encrypted with the integration_encryption_key your install generated locally.
  • Update state (which signed digest is active, history of applies).

Back it up with pg_dump (see upgrade.md for the recommended pre-upgrade snapshot) or with Borg / Restic against the volume mount point. The database is yours; nothing in it leaves your host.

Background workers (inside hivemind-server)

The server process runs several tokio::spawn'd loops in addition to the HTTP API:

  • Watchdog — sweeps stale agent heartbeats, enforces cost / runtime caps + the progressive 3-strike escalation, runs the every-5-minute system health check.
  • Plane sync — one-way pulls from a Plane workspace into the tasks table; no-op when PLANE_API_KEY is unset.
  • Schedules (HIVE-3) — 60-second tick loop that materializes directives from cron-driven schedules rows. Each schedule pairs a 5-field Unix cron with a directive template; the loop fires due rows, advances next_run_at to the next cron firing, and stamps the new directive's id on the schedule row. Missed windows are not backfilled. Disable globally with HIVEMIND_SCHEDULES_ENABLED=false. See self-hosting/api-reference.md for the CRUD endpoints.
  • Prekey replenish — sweeps provisioned chatalot bots and tops up their one-time prekey pools (HIVE-56).
  • Bot WS — maintains the chatalot bot WebSocket connections for inbound message handling (HIVE-57).

All of these are best-effort + per-row resilient: a single failure logs a warning and continues; nothing aborts the loop.

hivemind-updater — the managed-update sidecar

A tiny long-lived container that polls updates.seglamater.app/hivemind/releases/<channel>/manifest.json on your bundle's channel, surfaces new signed releases to the admin Updates page, and on operator approval pulls the new image digest + applies it in-place. It does not auto-apply — humans click Apply.

It also performs the safety checks the human can't easily do every time: cosign signature verification against the public key pinned at install time, image-digest pull (not floating tags), healthcheck gating + automatic rollback on failure. See upgrade.md.

Data flows

A user message to a public chatbot

  1. Browser → your reverse proxy → POST /api/v1/public/agents/chat/<slug> with the user's prompt.
  2. The server runs the input through rate limiting (per-IP-hash), input length enforcement, prompt-injection regexes, PII scrubbing.
  3. The server resolves the agent profile (tier 1 / public-capable only on the public endpoint), checks the cost cap, calls your LLM provider with your API key.
  4. The response is run through leak detection (private IPs, file paths, hostnames, ports) + PII scrubbing.
  5. The sanitized response is written to the audit log + returned.

The audit log lives in your database. You can browse it in the admin UI or pull it via GET /api/v1/agent-chat/audit.

A managed update

  1. The updater sidecar polls the manifest URL on your channel and notices 0.1.10 is now the current pinned digest.
  2. The admin Updates page surfaces the new version with cosign verification status + release notes.
  3. An operator clicks Apply in the UI.
  4. The sidecar pulls registry.seglamater.app/seglamater/hivemind-server@sha256:…, verifies the cosign signature against the pinned pubkey, sends a signed POST /v1/apply to the orchestrator over the internal updater_internal network (HMAC-signed with updater_token).
  5. The orchestrator drains the running server, recreates the container at the new digest, runs migrations on first start, waits for /api/v1/health to return ok, and either commits or rolls back automatically based on the healthcheck.

The Postgres volume is untouched — schema migrations are part of the new container's first start. See upgrade.md for the operator view.

Network exposure

Listener What Bound to Public?
hivemind-server :3000 (container) API + WebSocket + agent runtime Inside Compose network only No
Host :8585 Loopback bind from the server 127.0.0.1 No (your reverse proxy bridges it)
hivemind-db :5432 (container) Postgres Inside Compose network only No
hivemind-updater (no listener) Outbound only n/a n/a

Out-of-band: the server makes outbound calls to your LLM provider's API; the updater makes outbound calls to updates.seglamater.app (for the manifest poll) and registry.seglamater.app (for the image pull). Everything else is opt-in (chatalot integration, SSO IdP, etc.).

Trust + security model

Five concrete things to know:

  1. Your secrets stay on your host. ./secrets/ (mode 0700) on your install dir holds db password, admin API key, JWT signing key, cookie secret, integration encryption key, updater token, cosign pubkey. None of them are in the bundle Seglamater sends you; install.sh generates them locally on first run and never uploads. See bundle-spec.md for what IS in the bundle.
  2. Images are pulled by digest, not tag. Every install + every update pulls image@sha256:<hex>. Substituting a different image at the registry can't slip through; Docker verifies the manifest digest at pull.
  3. Updates are cosign-verified. Every release is signed with Seglamater's hivemind cosign key. Your install pins the public key's SHA-256 at install time (from the bundle); the updater refuses to apply a release that doesn't verify against the pinned key.
  4. Integration credentials are encrypted at rest. Chatalot bot tokens, etc., are sealed with ChaCha20-Poly1305 under your install's integration_encryption_key. The raw token is never stored.
  5. No telemetry, ever. The updater poll + image pull are the only outbound calls to Seglamater; they reveal only your channel
  6. your bundle's pinned version, never operational data. See license.md for the no-telemetry posture.

Where each piece is documented

Topic Doc
Fresh install walkthrough self-hosting/install.md
Configuring your LLM provider self-hosting/byok-llm.md
SSO via Authentik / OIDC self-hosting/sso-setup.md
Upgrading + rollback self-hosting/upgrade.md
Troubleshooting self-hosting/troubleshooting.md
What's in bundle.json self-hosting/bundle-spec.md
API reference self-hosting/api-reference.md
Chatalot integration integrations/chatalot.md
License terms self-hosting/license.md

What's NOT in this overview (yet)

  • High availability / clustering. v1 Hivemind is single-instance. HA Postgres + multiple server replicas behind a load balancer are on the roadmap; not yet supported as a documented topology.
  • Multi-tenant hosting. Hivemind is single-tenant by design. One organization per install. Customers who want isolation between business units run separate installs.
  • The Pulse-mesh integration. Seglamater is building a secure coordination plane (pulse.md in Seglamater's docs). When it lands, Hivemind will be a Pulse-mesh control-plane connector. Designed, not yet built.