hyperhive/docs/swarm/ui.md

# Swarm UI

The swarm's own web surface and the operator's day-to-day view: served by
the gateway on the **swarm apex** (`services.hyperhive.swarm.domain`),
readable only by operators. The per-hive dashboard, on each hive's own
domain, covers host-level detail for one hive.

## What it shows

| route                     | what                                                                                                |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| `/`                       | the hive directory, each hive with its last reported status                                         |
| `/agents`                 | every agent: status, config PR, wanted state; create agents, link forge, matrix and GitHub accounts |
| `/agents/<name>/terminal` | one agent's live terminal                                                                           |
| `/jobs`                   | the controller's job graph — where agent creation and credential mints show progress                |
| `/issues`                 | a cross-repo issue report                                                                           |

Everything it shows comes from [`swarm-controller`](../../swarm-controller/README.md).
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 three dialogs that write a credential for it
into the swarm secret store through swarm-controller. All three 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.
- **link a github account** — `PUT /api/hives/{hive}/agents/{agent}/github-account`
  with a personal access token, stored at `swarm/agents/<agent>/github-token`.
  One token per agent: linking again replaces it. The agent's
  `hive-agent-github-token` unit fetches it into `<state>/github-token`,
  the file its `gh` wrapper, git credential helper and GitHub notification
  poller read. A `github-token` already in place stays when the store holds
  none. What the token needs and how the agent uses it:
  [GitHub accounts](../integrations/github.md).

Where each credential lives and who reads it:
[`credentials.md`](credentials.md).

## Enabling

```nix
services.hyperhive.deploy.swarm-ui.enable = true;   # defaults to deploy.swarm-controller.enable
```

Derived from the controller rather than from `allSwarmServices`:
the UI is a view onto the controller's state and reaches it over that
daemon's socket, so the host that runs the controller is the host that
can serve the UI. A hive that merely _uses_ a swarm has nothing to serve.

The UI answers on `services.hyperhive.swarm.domain` and nothing else. It
shares that name with the swarm-controller it fronts — one service to a
reader and to a certificate — so there is no separate option to pin.

> The apex must differ from `services.hyperhive.domain`. The gateway's
> default server already answers for the hive domain, and two vhosts
> claiming one `server_name` don't error — nginx picks one — so this is
> an assertion rather than a runtime surprise.

## 🔑 You must be in the `admins` group

**This is the step that separates "protected" from "locked out."** The
vhost's `auth_request` asks authelia _"is there a session"_; the rule
that makes it mean _"is this an operator"_ is an `access_control` entry
requiring `group:admins`. An account without that group authenticates
fine and still gets bounced.

```sh
swarmctl user add <you> --email <you>@example.com --group admins
swarmctl user update <you> --add-group admins   # an account that already exists
```

`--email` isn't needed for the UI, but the forge won't create your account
without one → [setup.md § 2](../getting-started/setup.md#2--your-sso-account).

Why a group and not "any session": agents are authelia subjects too, so
_authenticated_ includes every agent in the swarm. The group is the only
thing standing between "an operator's page" and "anyone with a session."

## What it costs to be reachable

hyperhive publishes the apex to the hive's resolver like every other
swarm service, so agent containers can resolve it. That's deliberate and it's
not a hole: **reachability isn't the access control here.** An agent
that resolves the name and connects still has no operator session, and
the subrequest denies it.

## Quick links

The swarm UI's header carries a single 🔗 button, visible on every route,
opening a popover of links to other swarm-wide services. Backed by
`GET /api/links` (swarm-controller), which serves
`services.hyperhive.swarm.controller.links` (a `listOf { label, icon, url }`,
same shape as the per-agent `services.hyperhive.agent.dashboardLinks`).

Links to swarm services come from swarm-level options, so the list is the
same whichever host runs each service:

| link     | URL built from                                    |
| -------- | ------------------------------------------------- |
| Authelia | `services.hyperhive.swarm.authelia.domain`        |
| Grafana  | `services.hyperhive.swarm.grafana.domain`         |
| Metrics  | `services.hyperhive.swarm.victoriametrics.domain` |
| Logs     | `services.hyperhive.swarm.victorialogs.domain`    |
| Matrix   | `services.hyperhive.swarm.matrix.gatewayHost`     |
| Bao      | `services.hyperhive.swarm.bao.ui.domain`          |

`nix/host-modules/swarm-controller.nix` builds these entries. The Forge
entry, and `swarm-ui.nix`'s entry for this UI's own API docs, come from
those services' own modules, and only when the controller's host runs that
service. An operator can add entries 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. The homeserver's host
always serves the client at `/` on that vhost, so the entry is present
whenever the swarm names a gateway host.

The **Bao** entry opens the secret store's web UI, which admits members of
authelia's `admins` group only; see [`secrets.md`](secrets.md#the-browser-ui).

<details><summary>Adding a swarm service name: the two wiring sites</summary>

Adding a swarm service name means touching two things. Missing the
second ships as a different flavour of "works from the host, broken from
a container":

| site                         | file                                                                   |
| ---------------------------- | ---------------------------------------------------------------------- |
| vhost + `gateway.localNames` | the service's own module (for example `nix/host-modules/swarm-ui.nix`) |
| **certificate name**         | `nix/host-modules/swarm.nix` (`serviceDomains`)                        |

<!-- vale write-good.Passive = NO -->

The DNS record and the local-dev `/etc/hosts` entry need no separate
edit: both derive from `services.hyperhive.gateway.localNames`,
which a service's own module already has to push its domain into to be
resolvable — see `nix/host-modules/hive-gateway/dnsmasq.nix` and
`.../default.nix`'s `networking.hosts`. `vhosts.nix` itself is scoped to
the surface the hive's own domain serves (dashboard, per-agent routing,
matrix discovery); a swarm service declares its own vhost next to its
own options, the way `swarm-ui.nix` and `swarm-authelia.nix` do.

<!-- vale write-good.Passive = YES -->

⚠️ The certificate one is the hardest to predict and the most visible when
missed. `serviceDomains` is _both_ the `allowed_domains` the secret
store's `pki/roles/swarm-services` narrows to and the list each gateway's
leaf draws its SANs from (it carries the ones that host fronts),
and the apex is a **sibling** of `forge.<swarm>` / `chat.<swarm>` /
`auth.<swarm>`, not a parent — no CA in the hierarchy issues for it
implicitly. Left out, the vhost falls back to the hive leaf and the
swarm's front page opens with a name mismatch.

</details>

## Cross-references

- [`sso.md`](sso.md) — the authelia instance itself, and the user store.
- [`../networking/gateway.md`](../networking/gateway.md) — the full vhost map and TLS modes.