| Filename | Latest commit message | Latest commit date |
|---|---|---|
8e23feb01b
An operator links an agent's GitHub personal access token in the swarm UI
(LinkGithubAccountForm, "link github account" on /agents). swarm-controller's
PUT /api/hives/{hive}/agents/{agent}/github-account stores it at
swarm/agents/<agent>/github-token (swarm_secret_client::github), a flat leaf
under the agent's prefix that the agent's existing read grant already covers:
no policy change, and no list grant, since there is one token per agent.
In the agent, hive-agent-github-token (oneshot + 2-minute timer, as the agent
user, under its own store certificate, ordered before hive-github-notify)
reads that path and writes <state>/github-token, 0600 and agent-owned, the
file the gh wrapper, git credential helper and hive-github-notify already
read. It replaces the file by rename only when the bytes changed and never
deletes it: a hive-written github-token stays until a token is linked in the
swarm UI. It is installed only with a store address and
services.hyperhive.agent.github.enable.
Removed: the dashboard's CR3D3NTIALS page (credentials.html/js/css, its
build entries and H0M3 tile; GITHUB was its only tab), hive-c0re's
dashboard/matrix_accounts.rs with GET/POST /api/github-account,
priv_client::write_agent_github_token, the host socket's
SetAgentGithubToken and `hivectl github set-token`, and hive-priv's
WriteAgentGithubToken with write_agent_state_file, its only caller gone.
Docs: integrations/github.md and swarm/ui.md describe the swarm path,
swarm/credentials.md gains the store-path row, and the hive UI docs,
hivectl docs and security.md's hive-priv table drop the removed pieces.
Closes #4347
|
||
| .. | ||
| agent.md | ||
| css-vars.md | ||
| dashboard.md | ||
| design-guide.md | ||
| README.md | ||
| shape.md | ||
| terminal-rendering.md | ||
Dashboard & Web UI
The per-hive dashboard: approvals, container state and the rebuild queue for one hive. For swarm-wide day to day, see the swarm UI instead. If you want implementation detail — wire formats, DOM structure, event plumbing — see Dashboard layout, Per-agent page, Shape, and CSS theme variables below; this page only covers what you actually do here.
Where things are
Everything starts at the H0M3 hub, served at / — a grid of tiles
linking to every surface (Dashboard, Flow, Logs, Builds, Stats,
Settings, Core, Credentials). Every page links back to H0M3, so you're
never more than one step from the hub.
The dashboard itself (/dashboard.html) is where you'll spend most
of your time. It's a single page with exactly four tabs:
- SW4RM — every agent, live. This is the default tab and the one you'll check most.
- Y3R C4LL — anything waiting on you: pending approvals. If an agent needs a decision from you, it's here.
- P3RM1SS10NS — what tools and system-level access each agent has.
- SCH3DUL3S — scheduled prompts and agent self-reminders.
Everything else lives on its own page instead, all reachable from the
H0M3 hub: Flow (/flow.html, the raw live message stream across
the whole swarm), Logs (/logs.html, per-agent and host
journals), Stats (/stats.html, swarm-wide usage stats),
Builds (/builds.html, the rebuild queue and build history), and
Core (/core.html, tombstones and container resource use). Your local
browser preferences (notifications) live in the dashboard's Y3R C4LL
tab.
Each agent also has its own page — a full terminal view of that
agent's session, reachable by selecting its name anywhere in the
dashboard, or directly at /agent/<name>/ (or http://<host>:<port>/
if the gateway isn't in front).
The things you'll actually do
Check on an agent. SW4RM shows every container as a row: name,
whether it's running, what it's currently doing (a live status pill —
rebuilding…, starting…, or similar — while something's in flight),
and quick links (stats, screen, forge profile). Select the name to open
its terminal and watch it work in real time.
Approve something an agent is waiting on. Y3R C4LL is the one tab worth checking regularly — it's everything that needs you: approvals for config changes. The tab's count pill tells you at a glance if anything's pending.
Approve or reject a config change. Agent config changes (new packages, env vars, MCP servers) go through an approval queue rather than landing automatically — you'll see them on Y3R C4LL, with a diff of what's changing.
Start, stop, restart, or rebuild an agent. Select one or more
agents on SW4RM (select the icon) and use the selection bar, or use the
per-agent ⋮ menu on a single row. Rebuilding re-applies that agent's
current config; use it after approving a change, or whenever an agent
shows as "needs update."
Watch a build. BU1LDS shows the rebuild queue live, plus a streaming log of whatever's currently building. Useful right after approving a change or bumping a flake input.
Grant or revoke a tool/capability. P3RM1SS10NS is a checkbox matrix — rows are agents, columns are tool groups or capabilities. Nothing takes effect until you hit save all at the bottom of the tab; a save queues a rebuild for whichever agents actually changed.
Read an agent's logs. The Logs page's AGENT tab pulls a live
journald view for any agent + service; the per-agent ⋮ menu's
journal logs → link jumps straight there, pre-filtered.
Set up a schedule or check on a reminder. SCH3DUL3S covers both — recurring or one-shot prompts you schedule for one or more agents, and reminders agents have set for themselves.
More depth
Both the dashboard and the per-agent pages are SPAs sharing one
skeleton: GET / returns a static shell, /api/state returns JSON,
JS renders — no full-page reloads.
- Dashboard layout — every tab and standalone page, in full implementation detail: endpoint shapes, event wiring, exact badge-derivation rules.
- Per-agent page — the per-agent terminal, composer, side panel, slash commands, and per-agent endpoints.
- Shape (shared by both) — the SPA skeleton, SSE
multiplexing, terminal pane, listener bind, per-agent relative
paths,
data-asyncform pattern, side panel, atomic repaint. - CSS theme variables — the Catppuccin Mocha custom
properties declared once in
base.cssand the rule that per-page stylesheets reference (never redeclare) them. - swarm-ui design guide — visual language,
motion, theming, error-UX, and component-first principles for the
swarm-level Preact app specifically (not this page's dashboard/agent
UIs).
/componentson a running swarm-ui is the companion living demo of every primitive it references.
Implementation reading paths
Task-oriented jumps straight to the relevant section, for when you're touching the code rather than using the UI:
- "How does the dashboard SPA stay live without polling?" →
shape.md(SSE multiplexing, Worker-death self-heal, atomic repaint). - "What does a container row contain?" →
dashboard.md(Container row, Selection bar). - "What endpoints does the dashboard expose?" →
dashboard.md(Dashboard endpoints, Dashboard event channel). - "How does the per-agent terminal render tool calls?" →
terminal-rendering.md(full row taxonomy and dispatch walkthrough); for a high-level summary seeagent.md(Per-stream rendering). - "What slash commands does the agent accept?" →
agent.md(Terminal-embedded prompt). - "What are the per-agent HTTP endpoints?" →
agent.md(Per-agent endpoints). - "Which CSS variable do I use / where are colours defined?" →
css-vars.md(Palette, single-sourcebase.cssrule).