sencho/docs/features/dashboard.mdx

---
title: Dashboard
description: Real-time system health, stack load, configuration overview, fleet activity, and recent alerts for the active node.
---

The **Home** tab is the first thing you see after logging in. It surfaces the active node's overall health, live system metrics, the load on every stack, the on/off state of every automation and security feature, a fleet- or restart-activity panel, and the running alert tape, all on a single scrollable page.

<Frame>
  <img src="/images/dashboard/dashboard-overview.png" alt="Sencho Home dashboard showing the Healthy state masthead with its left-edge accent rail, four-tile resource gauge strip, paginated stack health table with Source and Port columns, Configuration Status card paired with Fleet Heartbeat, and the Recent Alerts feed." />
</Frame>

## Status masthead

The masthead at the top of the dashboard is the single place to read the node's current condition.

<Frame>
  <img src="/images/dashboard/status-masthead.png" alt="Status masthead in the Healthy state with a teal left-edge accent rail, the editorial state word, the meta line 'LOCAL · 4 NODES · LAST SYNC 0S', the reasons line 'All systems nominal', the RUNNING / CPU / MEM stat tiles, and an 8-alerts counter." />
</Frame>

It carries:

- A **state word** (Healthy, Degraded, or Critical) set in the editorial display face so the reader sees it first.
- A thin **accent rail** down the card's left edge that mirrors the state color: brand teal when Healthy, amber when Degraded, rose when Critical. The rail shimmers when Healthy and glows steadily otherwise.
- A **meta line** in uppercase mono tracking with the active node's name, the number of nodes registered to this Sencho instance, and the time since the last successful poll, for example `LOCAL · 4 NODES · LAST SYNC 1S`.
- A **reasons line** that names exactly which signals moved the state away from Healthy, for example `RAM 95% · 18 unread errors`. When the state is Healthy the reasons line reads `All systems nominal`.
- Three quick stat tiles on the right edge of the bar, hidden below the `md` breakpoint: **RUNNING** (`active/total`), **CPU**, and **MEM**.
- An alerts counter pinned to the far right, showing the number of unread notifications next to a bell icon and the word `alert` or `alerts`. The bell and count tint amber while at least one alert is unread.

The masthead's CPU stat tile tints amber once host CPU crosses 80% and stays amber even at 90% or higher. The MEM and RUNNING values stay neutral; the reasons line and the gauge strip below are where you read severity.

## Resource gauges

A single rail of four tiles shows the numbers that change minute-to-minute.

<Frame>
  <img src="/images/dashboard/resource-gauges.png" alt="Four-tile resource gauge strip: a CPU hero tile at 0.4% with the 'avg 0% last 10m · peak 0% @ 08:05 PM' caption and a 10-minute sparkline; a MEMORY tile at 15% in brand cyan with '2.4 GB / 15.6 GB' below; a DISK tile at 59% in brand cyan with '165.6 GB / 291.7 GB'; and a NETWORK tile reading '3.3 KB/s' with the rx/tx split and a rhythm sparkline." />
</Frame>

| Tile | What it shows |
|------|---------------|
| **CPU** (hero) | Current usage with the host's core count in the kicker, a 10-minute sparkline, and a caption with `avg X% last 10m · peak Y% @ HH:MM` |
| **MEMORY** | RAM usage as a percentage with a gauge bar and the exact `used / total` split below |
| **DISK** | Mount usage as a percentage with a gauge bar and the exact `used / total` split below |
| **NETWORK** | Total throughput per second with a `↓ <rx>/s · ↑ <tx>/s` breakdown and a live rhythm sparkline |

The gauge bars (and the corresponding numeric values) pick up amber at 80% and rose at 90%. The CPU sparkline uses brand cyan as the data color and does not mark the peak, since the caption already names the peak value and time. The network strip falls back to a dashed baseline when there is no traffic to plot.

While the dashboard is loading the CPU tile reads `--` and the caption shows `collecting metrics…`; bars and sparklines render once the first sample arrives.

<Note>
  **ZFS hosts:** the memory tile and host RAM alerts are ZFS ARC-aware. Reclaimable ARC cache is treated as available memory rather than used, so a large ARC does not inflate the gauge or trigger false low-memory alerts. See [ZFS ARC-aware host memory](/getting-started/configuration#zfs-arc-aware-host-memory) for how to expose ARC stats to a Docker install.
</Note>

## Stack health

A mono table of every stack discovered in the active node's `COMPOSE_DIR`, sorted so the stacks demanding attention sit at the top.

<Frame>
  <img src="/images/dashboard/stack-health.png" alt="Stack health table titled 'Stack health · 15 STACKS · SORTED BY LOAD' with pagination chevrons reading 1 / 2 and STACK / SOURCE / PORT / UP / CPU / MEM / CPU · 10m column headers, listing eight stacks (cloudflared, swag, plex, bazarr, radarr, sonarr, prowlarr, tautulli) each with a row tint, Local source, published port, uptime, current CPU and MEM, and a 10-minute CPU sparkline." />
</Frame>

The row itself carries the health tint (see below); there is no separate status-dot column. The columns are:

| Column | Description |
|--------|-------------|
| **STACK** | Stack name with an orange "Update available" badge when a newer image has been detected. When per-service status is known, the badge narrows to the outdated service name or a count (for example `2 updates`); hover for the full breakdown. The badge appears regardless of the sidebar indicator setting. Sortable. |
| **SOURCE** | `Git` when the stack is linked to a [Git source](/features/git-sources), `Local` otherwise |
| **PORT** | The stack's main published port, or `--` when it does not publish one |
| **UP** | How long the oldest running container has been up, in compact units (`s` / `m` / `h` / `d`); a stopped or never-started stack reads `--`. Sortable. |
| **CPU** | Latest aggregate CPU across the stack's containers. Sortable. |
| **MEM** | Latest aggregate memory across the stack's containers, formatted in MB or GB. Sortable. |
| **CPU · 10m** | Per-stack 10-minute sparkline tinted to match the row state; warn and error rows mark the peak with a contrasting accent color |

By default, rows sort by state (errors → warnings → healthy) and then by 10-minute peak CPU descending, so an exited stack always rises to the top and the noisiest healthy stacks float above the quiet ones (the header reads `sorted by load`). Click the **STACK**, **UP**, **CPU**, or **MEM** column header to sort by that column instead; the `sorted by load` label disappears once you do. Click the same header again to flip between ascending and descending. A row is tinted amber when its 10-minute peak CPU is at or above 80% or the stack is partially down (some but not all containers exited), or rose when the stack is fully exited or its peak CPU is at or above 90%. Click any row, or focus it and press <kbd>Enter</kbd> or <kbd>Space</kbd>, to jump to that stack's editor.

The table paginates at eight rows; chevrons appear in the header along with an `N / M` indicator when there is more than one page. When the active node has no stacks at all the card renders an empty state with a layered-disks glyph and the message `No stacks found. Create one from the sidebar.`

## Configuration Status

The Configuration Status card is the at-a-glance audit of every toggleable automation and security feature on the active node, so nothing is silently off when you expect it to be on.

<Frame>
  <img src="/images/dashboard/configuration-status.png" alt="Configuration Status card with four sections: Notifications (Channels 'Discord', Alert rules None, Routing None, Mute Rules None), Automation (Auto-heal policies '1 / 1 active', Auto-update schedules '1 / 1 active', Webhooks None, Scheduled tasks '1 active'), Security (MFA Off, SSO Off, Trivy installed Installed, Scan policies None), and Backups & Thresholds (Recovery Vault active, Alert thresholds Off, Crash detection On)." />
</Frame>

The card is divided into four sections.

### Notifications

| Row | What it shows |
|-----|---------------|
| **Channels** | The list of enabled delivery agents from `Discord`, `Slack`, `Webhook`, and `Apprise`, joined by commas; reads `None` when no agent is enabled |
| **Alert rules** | Total per-stack alert rules in effect, formatted `<n> rules` |
| **Routing** | Number of enabled routing rules that direct categories to specific agents, formatted `<n> routes` |
| **Mute Rules** | Number of enabled notification-suppression rules, formatted `<n> rules`. See [Mute Rules](/features/alerts-notifications#mute-rules). |

### Automation

| Row | What it shows |
|-----|---------------|
| **Auto-heal policies** | `<enabled> / <total> active` for crash-recovery policies across all stacks; reads `None` when no policies exist |
| **Auto-update schedules** | `<enabled> / <total> active` count of `Auto-update Stack` / `Auto-update All Stacks on Node` rows configured for this node; reads `None` when none are configured |
| **Webhooks** | Active inbound deploy webhooks tied to Git Sources or stacks, formatted `<n> actives` |
| **Scheduled tasks** | Active scheduled operations (backups, restarts, scripts), formatted `<n> actives` |

### Security

| Row | What it shows |
|-----|---------------|
| **MFA** | `On` when TOTP is configured for the signed-in operator, `Off` when configured but disabled, `Not set up` when there is no MFA secret on file |
| **SSO** | The active SSO provider name (`OIDC`, `Google`, `GitHub`, `Okta`, `LDAP`); reads `Off` when SSO is not enabled |
| **Trivy installed** | `Installed` when a Trivy scanner binary is available on this node, `Not installed` otherwise |
| **Scan policies** | Count of enabled vulnerability scan policies on the active node, formatted `<n> policies`; reads `None` when no policy is enabled |

### Backups & Thresholds

| Row | What it shows |
|-----|---------------|
| **Recovery Vault** | The active recovery target: `Recovery Vault` (Admiral), `Custom S3` (with ` (auto)` appended when auto-upload is enabled), or `Disabled` |
| **Alert thresholds** | The current host thresholds, formatted `CPU x% · RAM y% · Disk z%`, or `Off` when host threshold alerts are disabled |
| **Crash detection** | `On` when global container-crash notifications are enabled, `Off` otherwise |

Click any row to jump directly to the settings section that manages it.

The card refreshes automatically every 60 seconds. It also refreshes immediately whenever a scheduled task is created, edited, toggled, or deleted, so the **Scheduled tasks** row (and the rest of the card) reflects that change within a second. Other changes covered by this card, such as switching the cloud backup provider or enabling SSO, update on the next 60-second tick.

## Activity panel

To the right of Configuration Status, the dashboard shows one of two activity panels:

- **Fleet Heartbeat** when at least one remote node is registered and your role has the `node:read` permission.
- **Stack Restarts (7d)** when this Sencho instance manages only the local node, or when your role lacks `node:read` (so a deployer-level role never sees a fleet card it cannot load).

### Fleet Heartbeat

<Frame>
  <img src="/images/dashboard/fleet-heartbeat.png" alt="Fleet Heartbeat card with the radio-tower kicker '4 NODES' on the right, listing four entries with green status dots: Local with the brand 'LOCAL' pill and 16 containers; Opsix with 4 containers and 75 ms latency; Pitt-Moba with 3 containers and 65 ms latency; SLX-Mars with 4 containers and 243 ms latency." />
</Frame>

The header carries a radio-tower icon, the total node count, and a `<n> unreachable` callout in destructive red whenever any node is offline. Each row shows:

- A **status dot**: green when the node has answered a recent heartbeat, amber when its state is unknown, rose when offline or unreachable.
- The **node name** in mono.
- A **LOCAL** brand pill on the local node.
- The **active container count** for that node, returned alongside the latency in the fleet-overview payload.
- A **latency** column on the right of online proxy nodes, in milliseconds. Pilot-agent nodes (which receive their commands over an outbound tunnel rather than being polled) read `n/a` since round-trip latency is not meaningful for them.
- A **last-seen** timestamp on offline rows; pilot-agent nodes use their tunnel heartbeat, regular proxy nodes use the local Sencho instance's last successful contact.

The card refreshes every 30 seconds. When you have not registered any node it shows a `No nodes registered.` empty state.

### Stack Restarts (7d)

When the dashboard renders this variant, the same column shows a 7-day rolling restart map. Each stack with at least one restart in the window appears as a row carrying:

- The **stack name** in mono.
- A **category badge** for the dominant restart reason: `crash` (rose), `auto-heal` (green), or `manual` (brand). Ties resolve in favor of `crash` over `auto-heal` over `manual`.
- The **total restart count** on the right, with a proportional fill bar tinted to match the badge.

Stacks with zero restarts are not listed individually; they are summarized in a single footer row that reads `<n> stacks stable`. When no stack has restarted in the window the card shows a green check and `No restarts in the last 7 days.` This panel refreshes every five minutes.

## Recent Alerts

The bottom-most card on the dashboard collects every triggered notification on the active node, sorted by recency.

<Frame>
  <img src="/images/dashboard/recent-alerts.png" alt="Recent Alerts card listing eight local, unbadged info-level rows about stack image updates and auto-update runs for plex, radarr, and swag, each carrying a relative timestamp such as '4h ago', with a 'Clear All Notifications' button anchored at the bottom right. No pagination chevrons appear because the feed holds exactly eight entries." />
</Frame>

Each row shows:

- A **severity icon**: an info circle (brand) for `info`, a warning triangle (amber) for `warning`, an octagonal alert (rose) for `error`.
- An optional **node badge** when the alert came from a remote node, showing the source node's name. Local-node alerts skip the badge.
- The **alert message**, dimmed once the alert has been read.
- A relative **timestamp** on the right, for example `2h ago`.

A **Clear All Notifications** button is anchored at the bottom right of the card. Clicking it deletes every alert in the feed by issuing a `DELETE /api/notifications` against each node that contributed an entry; while the request is in flight the button label switches to `Clearing...` and the button disables. The button stays visible while there are alerts; when none remain the card collapses to a green check and the message `No recent alerts.`

The list paginates at eight rows; chevrons and an `N / M` indicator appear in the header when there is more than one page.

Per-stack alert rules live on each stack's **Monitor** sheet; delivery channels and severity routing are configured in **Settings · Notifications**. See [Alerts and notifications](/features/alerts-notifications) for channel setup, per-stack rules, mute rules, and the routing engine.

## On a phone

<Frame>
  <img src="/images/dashboard/dashboard-mobile.png" alt="Mobile dashboard masthead reading 'Healthy' with a status dot, node switcher, and '15 stacks · 15 up · 0 dn · sync 0s' meta line, followed by a CPU hero card, a mem/disk/net three-up strip, and a Stack Health list of six rows with a 'view all' link." />
</Frame>

The phone layout condenses the dashboard to what fits a single thumb-scroll: the masthead (state word, status dot, and a compact `<n> stacks · <n> up · <n> dn · sync <age>` meta line), the CPU hero card with its sparkline, a three-up memory/disk/network strip, and a **Stack Health** list capped at six rows with a **view all →** link to the full stack list. Rows show only the stack name, its host, a 10-minute sparkline, and current CPU; tap a row to open that stack's editor.

Configuration Status, the Fleet Heartbeat / Stack Restarts panel, and Recent Alerts are desktop-only; open Sencho on a wider screen to see them. Notifications stay reachable from the bell icon in the mobile masthead.

## How health is derived

The masthead's state word and reasons line both come from a single rule against five signals: host CPU, host RAM, host disk, exited container count, and unread `error`-level notifications.

| State | Meaning |
|-------|---------|
| **Healthy** | All five signals nominal. CPU, RAM, and disk are all under 80%, no container is in the `exited` state, and there are no unread error alerts. |
| **Degraded** | At least one of CPU, RAM, or disk is at or above 80%, OR at least one container is in the `exited` state, OR at least one unread error alert exists. |
| **Critical** | At least one of CPU, RAM, or disk is at or above 90%, OR at least one container is in the `exited` state AND at least one unread error alert is present at the same time. |

Every signal that contributes to a non-Healthy state appears in the reasons line, separated by middle dots (`·`), so you can read the cause directly without hovering anything.

## Refresh cadence

The dashboard is built from several independent polling loops so that fast-moving values stay live without flooding the API for slowly-changing ones.

| Surface | Polling cadence |
|---------|-----------------|
| Container counts and host system stats (masthead, gauges) | 5 seconds |
| Stack statuses (status dots and uptime in the table) | 10 seconds |
| Historical metrics (CPU sparklines and per-stack 10m series) | 60 seconds |
| Configuration Status card | 60 seconds |
| Fleet Heartbeat | 30 seconds |
| Stack Restarts (7d) | 5 minutes |
| Recent Alerts | Pushed live over the notifications WebSocket, with a 60-second safety-net reconcile poll |

In addition, every Docker container event (start, stop, die, restart, health-status change) on the active node fires a `sencho:state-invalidate` browser event that immediately refetches container counts, system stats, and stack statuses, so the masthead, gauges, and stack health table react in well under a second instead of waiting for the next polling tick. The Configuration Status card ignores these container-level events; it only reacts early to scheduled-task changes (see the section above), so it stays on its 60-second cadence for everything else.

When you switch the active node from the node switcher, the dashboard resets every panel to its loading state and starts a new round of fetches against the new node so you never see stale data from the previous one.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Stack health is empty even though I have stacks on disk">
    The table reads from the active node's `COMPOSE_DIR`. If you mounted the compose volume to a different path inside the container, set the environment variable in your `docker-compose.yml` so it matches what is on the host. Per-node overrides live on the **Compose directory** field of the node entry; the resolution chain is `node.compose_dir` → `process.env.COMPOSE_DIR` → `/app/compose`. After fixing the mount or the field, the table populates on the next 10-second poll.
  </Accordion>
  <Accordion title="Fleet Heartbeat shows a node as 'unreachable' or with a red dot">
    The Heartbeat card calls `/api/fleet/overview` on the local Sencho instance every 30 seconds; that endpoint records the last contact for each remote node. A red dot means the local instance has not been able to reach that node's `api_url`, or that the long-lived API token attached to the node entry has expired or been revoked. Re-test the connection from **Settings · Nodes**, regenerate the token on the remote instance, paste the new value into the node form, and the heartbeat clears on the next tick. See [Multi-node management](/features/multi-node) for the full setup flow and [Pilot agent](/features/pilot-agent) when the offline node is in agent mode.
  </Accordion>
  <Accordion title="A pilot-agent node shows 'n/a' for latency">
    Pilot-agent nodes connect outbound to the primary over a reverse tunnel, so there is no synchronous request-response loop to measure. The Heartbeat card uses the tunnel's last heartbeat to set the dot color, and intentionally renders `n/a` in the latency column. If the dot is red, check the agent container's logs for the first `[Pilot]` line and confirm the agent can reach the primary URL it is dialing. See [Pilot agent](/features/pilot-agent).
  </Accordion>
  <Accordion title="Configuration Status still shows the old value after I changed a setting">
    The card refreshes every 60 seconds on its own schedule. Creating, editing, toggling, or deleting a scheduled task also dispatches a live invalidation that the card picks up within a second. Other settings changes (cloud backup provider switch, SSO provider change, alert rule edit, agent toggle) update on the next 60-second tick. If the row stays stale after a minute, hard-reload the dashboard tab to force a fresh fetch.
  </Accordion>
  <Accordion title="The masthead shows a 'metrics stale' chip next to the node name">
    The chip appears after three consecutive failures of the live metrics endpoints (`/api/stats` or `/api/system/stats`), which usually means the Docker socket is unreachable from this Sencho instance or the metrics service has stopped. The dashboard keeps polling on every cycle; the chip describes the freshness of the visible numbers, not the polling cadence. The chip clears on the first successful response once both endpoints are within the threshold. Check the Docker daemon status on the active node first, then the Sencho container logs for `[Dashboard]` lines if the chip persists.
  </Accordion>
  <Accordion title="Recent Alerts shows '1 / 12' but I want to scrub through history">
    The card paginates at eight rows. Use the chevrons in the header to flip pages. The full alert history (with filters and search) lives in the bell menu in the top bar; the dashboard card is a tape view of the latest entries on the active node. **Clear All Notifications** deletes the whole feed in one call, fanned out across every node that contributed an entry.
  </Accordion>
  <Accordion title="The masthead reads 'Critical' but my CPU is low">
    Critical can fire on RAM, disk, or the combination of any exited container with an unread error alert, not only on CPU. Read the reasons line right under the meta line; it lists every signal pushing the state up. Common cases: RAM at or above 90% from an oversized service, disk at or above 90% from runaway log retention, or a crashed container that no one has acknowledged in the alerts panel.
  </Accordion>
  <Accordion title="The dashboard feels sluggish on a large deployment">
    Toggle **Developer mode** under **Settings · Operations · Developer Diagnostics**. Both dashboard endpoints then emit a `[Dashboard:debug]` line in the Sencho container logs for every request, reporting elapsed milliseconds and the contextual fields (`nodeId`, row count, `days` window). Use the timings to identify whether the Configuration Status payload or the stack-restarts query is the bottleneck. Disable developer mode when you are done to keep the log volume manageable.
  </Accordion>
</AccordionGroup>