Hive architecture

The technical picture of Hive for builders and auditors: the portal daemon, the proxy that federates the stack, the landing gate, and the trust posture. Grounded in the Hive technical manual.

Related:

• What is Hive?
• Hive command reference

---

#Overview

Hive is a portal daemon plus a server-side backend-for-frontend proxy. It is its own repository and npm package, @legioncodeinc/hive, and it serves the whole Apiary dashboard from one origin. The dashboard is a React single-page app owned outright by Hive; the server is built on Hono and runs on Node 22 or newer.

#Binding

Hive binds 127.0.0.1:3853. The host and port are hard-pinned in the shared constants, with no environment override, so the portal is reachable only from the local machine.

#The backend-for-frontend proxy

The browser makes same-origin fetches only, to /api/*, /setup/*, and /health. Hive's server resolves which daemon owns each request and fetches it over local loopback. The routing rule is simple: Nectar owns /api/hive-graph and its sub-paths, and Honeycomb owns everything else. The three workload addresses are Honeycomb on 127.0.0.1:3850, Doctor on 127.0.0.1:3852, and Nectar on 127.0.0.1:3854.

This design means no workload daemon needs cross-origin headers, and no daemon port is ever handed to a browser. An earlier design had the browser fetch each daemon directly, which forced cross-origin handling onto every daemon and pushed the loopback-trust boundary into the browser; the proxy replaced it.

#Health, from Doctor

Hive never probes workload health endpoints itself. It reads Doctor's status feed server-side for the landing decision, and relays Doctor's live health stream to the browser as server-sent events. Five locked service states are derived: error, degraded, starting, warming, and active.

#The landing gate

A gate runs ahead of every route: health first, then auth. An unhealthy stack redirects to the readiness screen. A logged-out visitor redirects to the sign-in screen. Otherwise the request is served. The gate fails closed: any failure of the auth check redirects to sign-in, and redirect targets are hard-coded literals so there is no open-redirect surface.

#Auth, by pass-through

Hive mints and stores no credential. "Logged in" is Honeycomb's authenticated bit, which reflects the presence of the credentials file on your machine. Hive reads it and never writes it. The proxy forwards the browser's own headers, minus a fixed hop-by-hop strip set.

#Supervision and single-instance guard

Doctor probes Hive's /health every 30 seconds and restarts it on a crash. Hive holds an exclusive lock file and writes a pid file, so a second start exits cleanly and a stale lock from a dead process is reclaimed. Hive installs as an OS service on each platform: a launch agent on macOS, a user service on Linux, and a scheduled task on Windows.

#Trust posture

The trusted loopback set is exactly the local host names. Every server-side fetch re-checks its target against that set and refuses to follow redirects. Hive persists nothing of its own beyond the pid and lock pair and a small telemetry dedupe ledger.

#Health endpoint

A request to /health returns liveness as JSON for probes, or serves the dashboard's health page when the request accepts HTML.

#License

Released under the GNU Affero General Public License, version 3.0 or later.