---
module: fleet.modules
title: Modules
tab: Internal
order: 20
audience: internal
---

> **Internal · ops/support.** Written 2026-07-01 from `hiveops-fleet` source. Verify against code before relying on specifics.

## What this screen actually is
The **Agent Modules** screen (`FleetModules.svelte`) is a mostly **static reference catalog**. The list of 16 modules, their display names, descriptions, and the four categories (**Data Collection / Monitoring / Fleet Management / Updates**) are **hardcoded in the frontend** (`MODULE_CATALOG` const in `FleetModules.svelte`) — they are not fetched from the backend.

The only live data is the per-module status badge counts (running / disabled / failed / not reporting), fetched from `GET /api/fleet/modules/summary` on `hiveops-fleet` (port 8097).

## ⚠️ Known state: status badges are not wired up
`FleetApiController.getModuleSummary()` currently returns a **hardcoded empty list** (`return List.of();`). Because of this:
- The screen renders all 16 module cards with names + descriptions, but **no status badges appear** (the `{#if summary}` block in the component never matches, since `$moduleSummary` is always empty).
- This is expected current behaviour, **not** an outage. If someone reports "no running/failed counts on the Modules screen," that is the stub endpoint, not a broken agent or a data-sync problem.

## Roles required
- **Read (this screen):** `hasAnyRole('USER','CUSTOMER','ADMIN','MSP_ADMIN','BCOS_ADMIN')` on `GET /api/fleet/modules/summary`. Any logged-in fleet user can view it.
- There are **no admin-only mutating actions** on this screen — it is strictly read-only. There is nothing to enable, disable, or approve here. Module enablement is driven by agent config (`CONFIG_UPDATE` fleet tasks / config server), not from this view.

## First things to check when it misbehaves
1. **Page loads but no badges** → expected: `/modules/summary` is a stub returning `[]`. Not a bug to escalate for a customer.
2. **Page blank / cards missing entirely** → frontend issue. The catalog is client-side, so a blank page means the SPA failed to load, not a backend outage. Check the fleet frontend bundle / nginx for `fleet.bcos.cloud`.
3. **500 / 401 / 403 on `/modules/summary`** → auth plane. `/api/fleet/**` (non-internal) uses the JWT `JWT_SECRET`; a 401/403 means a bad/expired JWT or a role the token lacks. Confirm the caller's JWT role is one of the allowed roles above.
4. **404 on `/modules/summary`** → wrong base path or service down. Confirm requests hit `hiveops-fleet` at `/api/fleet` (nginx location block), not a stale blue/green backend. `curl http://localhost:8097/actuator/health` on the services VM.
5. **Descriptions look wrong / a module is missing** → it's a frontend catalog edit, not data. Update `MODULE_CATALOG` in `FleetModules.svelte`, rebuild the fleet frontend.

## Common failure modes + fixes
| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| No status badges on any card | `/modules/summary` returns `List.of()` (stub) | Expected today; wiring the real summary is a backend change, not an ops fix |
| Whole page blank | SPA/bundle didn't load | Check nginx for `fleet.bcos.cloud`, rebuild/redeploy fleet frontend |
| 401/403 on the API call | Bad/expired JWT or missing role | Re-auth; confirm role is USER/CUSTOMER/ADMIN/MSP_ADMIN/BCOS_ADMIN |
| 404 on the API call | Stale blue/green backend or wrong path | Recheck nginx `/api/fleet/` upstream; hit active fleet color |
| Module counts look stale (if/when wired) | Would depend on the future data source (agent status reporting) | N/A today — no live source exists yet |

## Notes for support
- This screen does **not** tell you whether a specific ATM has a module running — it is a fleet-wide catalog/summary, and the summary is currently empty. To check a real ATM's module state, look at agent config / fleet tasks / the device record, not here.
- Related client methods `getModules()` → `/modules` and `getModulesByAtm()` → `/modules/atm/{id}` exist in the fleet API client but have **no matching backend endpoint** in `FleetApiController` and are **not** used by this screen — do not point people at them.
