---
title: NervHQ and its API
scope: 3dmk
type: documentation
subject: nervhq
group: Systems
status: current
version: "2.1.3"
source: https://3dmk.com/documentation#nervhq
author: Nick Olson
contact:
  email: 3dmk@3dmk.com
  site: https://3dmk.com
license: CC BY 4.0
license_url: https://creativecommons.org/licenses/by/4.0/
attribution: Nick Olson, 3dmk.com
---

# NervHQ and its API

NervHQ is the operations dashboard for the stack. It shows machines, services, projects, agent sessions, work queues, code activity, and system health on one screen. The NervHQ API gathers that data from the rest of the stack. Together they show what runs and what needs attention without a query to each service.

## Role

The dashboard, `core-nervhq`, is a React single-page application written in TypeScript. It runs as static files that nginx serves, with no server-side code.

The API, `core-nervhq-api`, is a FastAPI service written in Python. It coordinates collector daemons, scheduled jobs, PostgreSQL storage, Redis caching, and WebSocket event streams. It also records agent sessions. Both members run on core-docker-1.

## Parts

The dashboard groups its views into five sections:

- Dashboard: the daily log, sessions, and a Magi graph viewer across all themes

- Project management: Scrolls initiatives, epics, stories, tasks, and bugs

- Seele: a document reader, a searchable library, and a map of the corpus colored by theme

- Themes: one dashboard per theme with sessions, GitHub activity, projects, Docker, and action items

- Admin: system settings, theme management, and GitHub repository management

The API runs these parts inside one service.

| Part | Job |
|---|---|
| Collector daemons | Poll GitHub, infrastructure health, and Nexus |
| Scheduler | Fires stored jobs and sends each task to an idle daemon with the matching capability |
| Database worker | Writes and reads PostgreSQL records |
| Cache worker | Updates Redis and adds each change to a 60-second event buffer |
| Session ingester | Sums token usage per session, model, and agent every minute |
| Routers | Serve the cache, sessions, action items, the daily log, notepad entries, and Magi graph files |

The daemons hold no database access. Every result returns to the API over a WebSocket.

## Data

The API stores durable records in PostgreSQL. A Redis cache serves the dashboard from two groups of tables.

| Group | Tables | Contents | Expiry |
|---|---|---|---|
| Database-backed | 24 | GitHub activity, sessions, projects, action items, settings, and the daily log | None |
| Infrastructure | 10 | Health and package data from the collectors | 300 seconds |

Session data covers each session’s activity, summary, changed repositories, and token usage by model and agent. Infrastructure entries expire when the collectors stop reporting. The dashboard mirrors the same 34 tables in its own store.

## Connections

The API exchanges data with these systems:

- Model Context Protocol (MCP) gateway: It sends a typed close event at the end of each session.

- GitHub: Sync daemons collect repositories, branches, tags, commits, and changed files.

- Scrolls: The API passes each work-tracking request to the Scrolls service.

- Registry: The dashboard shows each repository’s development host from the Registry.

- Nexus: A collector inventories packages. It checks proxied packages against Open Source Vulnerabilities (OSV) data.

- Consul and Vault: The health collector reads the Consul service catalog and Vault’s status.

One transaction records each closed session with its activity, summary, and changed repositories. Database writes then update Redis. WebSocket events refresh the dashboard without a full reload. Token usage reaches the dashboard within 6 minutes of each agent turn.