vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs(web-ui): scope dashboard.md to what the hive UI renders

Browse source 
Per mara's review: the hive UI doc covers only what hive-c0re's pages
render. Removed the M4TR1X page section (the hive gateway redirects
/matrix/ to the swarm matrix client, which the swarm UI's quick links
open), the swarm-UI forge/matrix account-linking lines from the
CR3D3NTIALS section, the infra-services hivectl paragraph, and the H0M3
Matrix/Forge absence line. Added a single pointer to docs/swarm/ui.md,
and stated the account-linking and Matrix quick-link facts there.

Refs #3902
This commit is contained in:
atlas 2026-10-02 12:56:54 +02:00 • committed by mara
commit cabde572e9
2 changed files with 37 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

28
docs/swarm/ui.md
View file

@ -19,6 +19,27 @@ Everything it shows comes from [`swarm-controller`](../../swarm-controller/READM
An agent created here or with `swarmctl agent create` starts `paused`; set it
`up` from its card.
### Linking external accounts
Each agent on `/agents` opens two dialogs that write a credential for it
into the swarm secret store through swarm-controller. Both are blind
set/update actions: no route lists linked accounts or hands a token back.
- **link a matrix account** — `PUT /api/hives/{hive}/agents/{agent}/matrix-accounts/{account}`,
either a pasted bearer token or a user id + password that
swarm-controller logs in with, storing the token it gets back.
- **link a forge account** — `PUT /api/hives/{hive}/agents/{agent}/forge-accounts/{label}`
with a forge URL and an access token, stored at
`swarm/agents/<agent>/forge/<label>`. The agent's
`hive-agent-forge-accounts` unit fetches it into
`<state>/forge-<label>-token` and `<state>/forge-<label>.json`, the files
`hive-forge -f <label>` reads. The unit never deletes a pair: linking
the same label again overwrites both files, and a pair whose label the
store doesn't list stays untouched.
Where each credential lives and who reads it:
[`credentials.md`](credentials.md).
## Enabling
```nix
@ -82,6 +103,13 @@ controller's host — `swarm-authelia.nix`, `hive-matrix.nix`,
a nix-only change to that service's module, or an operator adding an entry
directly. An empty list hides the button.
The **Matrix** entry opens the swarm's matrix web client (fluffychat,
`services.hyperhive.deploy.matrix.gui.package`) at the homeserver's
gateway host, `chat.<swarm domain>` by default. `hive-matrix.nix` adds it
only when `services.hyperhive.deploy.matrix.gui.enable` is on and the
homeserver has a gateway host, the same condition under which that vhost
serves the client at `/`.
<details><summary>Adding a swarm service name: the two wiring sites</summary>
Adding a swarm service name means touching two things. Missing the

46
docs/web-ui/dashboard.md
View file

@ -3,13 +3,17 @@
> Part of [Web UI](README.md). See also:
> [Shape (shared)](shape.md) · [Per-agent page](agent.md)
This page covers the per-hive UI that hive-c0re serves. Swarm-wide
surfaces — the agent roster, agent creation, linking external forge and
matrix accounts, the controller's job graph — are on the
[swarm UI](../swarm/ui.md).
hive-c0re serves the dashboard at `/dashboard.html` (with the home page at `/`).
It has a fixed chrome header at the top and a `<main>` that shows exactly
one tab pane at a time. The URL hash (`#swarm`, `#call`,
`#permissions`, `#schedules`) drives which pane is
active; hash changes don't reload the page. FL0W, L0GS, and the optional
M4TR1X client are separate pages reachable from the H0M3 hub at `/`, not
active; hash changes don't reload the page. FL0W, L0GS, and the other
standalone pages are reachable from the H0M3 hub at `/`, not
from the dashboard tab strip.
**Chrome header** (fixed, overlays the active tab pane):
@ -17,8 +21,8 @@ from the dashboard tab strip.
at `/`. Every surface links back to the hub rather than to each other.
- **Tab strip**: `◆ SW4RM ◆`, `◆ Y3R C4LL ◆`, `◆ P3RM1SS10NS ◆`,
`◆ SCH3DUL3S ◆`. In-page tabs only — the SYST3M panels live on the
standalone **C0R3** page (`/core.html`), and FL0W / L0GS / ST4TS /
M4TR1X live on their own pages too, all reachable from the
standalone **C0R3** page (`/core.html`), and FL0W / L0GS / ST4TS
live on their own pages too, all reachable from the
H0M3 hub (not the tab strip). Count pills on SW4RM
(container count), Y3R C4LL (pending approvals + unread
operator messages), and SCH3DUL3S (active schedules).
@ -165,11 +169,6 @@ last-sampled value (`null` until the first sample). Network isn't tracked
per container — see `docs/networking/network.md` for the current
per-agent netns model.
Hive infrastructure services (`hive-ci`, `hive-forge`, `hive-gateway`,
`hive-matrix`) have no dashboard panel — `hivectl stop`/`start`/`restart`
is the only control surface, a separate host-admin-socket path with no
HTTP route and no agent-facing equivalent.
## BU1LDS page (`/builds.html`)
The build lifecycle hub — rebuild queue, live build log, meta inputs,
@ -293,9 +292,7 @@ on the H0M3 hub, same minimal chrome as `/logs.html` (a `← home` back-link
than `/core.html`'s plain title. Its own esbuild bundle
(`credentials.js`); no SSE — it reads `/api/state` once for the (shared)
agent picker and otherwise works off purpose-built endpoints per tab.
One sub-tab:
Link an external matrix account from the swarm UI (`LinkMatrixAccountForm` → swarm-controller).
One sub-tab, GITHUB.
### GITHUB tab
@ -315,8 +312,6 @@ Provisioning posts `POST /api/github-account` (form-encoded `agent`,
`application/problem+json` with the message in `detail`. The token is never
echoed back in either direction.
Link an external forge account from the swarm UI (`LinkForgeAccountForm` → swarm-controller); the agent fetches it into the files `hive-forge -f <label>` reads. A `forge-<label>-token`/`forge-<label>.json` pair already on disk is never deleted, so `hive-forge -f <label>` keeps reading it until a swarm-UI link under that label overwrites both files (`nix/agent-modules/forge-accounts.nix:11-13,159-176`).
## P3RM1SS10NS tab
Per-agent permission configuration. Two sections, each rendered as a
@ -536,26 +531,6 @@ they're enabled there, because `NOTIF.show()` in
`hyperhive.notify.muted` localStorage key, not on the buttons
existing in the page DOM.
## M4TR1X page (`/matrix/`, optional)
A static matrix web client (default `pkgs.fluffychat-web` rebuilt
with `--base-href /matrix/`, swappable via
`services.hyperhive.deploy.matrix.gui.package`) served by the hive-gateway
nginx container at `/matrix/` when
`services.hyperhive.deploy.matrix.gui.enable` is on (defaults to
`matrix.enable`). c0re signals availability via the
`HIVE_MATRIX_GUI_ENABLED` env var → `state.matrix_gui_enabled` in
`/api/state`; the gateway does the actual static serving.
The operator reaches it from the swarm-ui LinksMenu (see
`docs/swarm/ui.md::Quick links`), and logs in once with the
in-host tuwunel homeserver URL (`http://localhost:8008` or whatever
the matrix module exposes).
The unified nginx-front re-root to
`https://chat.${hyperhive.swarm.domain}` + `.well-known/matrix/client`
autodiscovery lives in `docs/networking/gateway.md` (atlas's lane).
## FL0W page (`/flow.html`)
A dedicated full-page terminal (not a tab pane — a separate HTML
@ -607,9 +582,6 @@ from the shared theme (Catppuccin Mocha via `common.css` + `theme.css`).
`home.js` fills the swarm/hive identity line at the top. All dashboard
sub-pages include a `← Home` back-link for navigation.
No Matrix or Forge tile here — the operator reaches those surfaces
(`/matrix/`, the forge's own public URL) directly, not via the dashboard UI.
## L0GS page (`/logs.html`)
A dedicated log-viewer page (not a tab pane — a separate HTML page),