ai-dashboard

Operator dashboard for an AI nervous system. One HTTP surface that aggregates organ health, proxies API calls, tails network events, and stitches the rest of the ai-* family into a single page.

Lifted from raj-sadan, where it was the operator-facing layer over four organs (mind/senses/memory/knowledge). Generalized so any multi-service system can drop in a registry.toml and get a working dashboard.

Status: v0.1.0. Single-page chrome, registry-driven organ tiles, proxy passthrough, SSE network log, 4 MCP tools. Stub organ client is the default — runs out of the box without anything else listening.

What it does

Surface	Where
Organ status grid	/ (index page, auto-refreshes)
Aggregate health	GET /api/organs/health
Single organ health	GET /api/organs/:organ/health
Network event log (tail)	GET /api/network/events?limit=N
Network event stream	GET /api/network/stream (SSE)
Per-organ proxy	ALL /api/<organ>/* → registered URL
Registry view	GET /api/meta
MCP tools	stdio: dashboard_health, dashboard_organ_health, dashboard_tail_events, dashboard_meta

The dashboard never holds organ logic — it only tiles, proxies, and observes.

Install

npm install @vraj0703/ai-dashboard

Optional peer dependencies (install only what you need):

npm install @iarna/toml                  # if you use a .toml registry
npm install @modelcontextprotocol/sdk zod  # if you use the MCP server

Use

CLI

ai-dashboard --registry ./registry.toml
ai-dashboard --registry ./examples/simple/registry.toml --port 4000
DASHBOARD_USE_REAL_ORGAN_CLIENT=1 ai-dashboard --registry ./registry.toml

Flag	Env	Default
--registry <path>	DASHBOARD_REGISTRY	(required)
--port <n>	DASHBOARD_PORT	registry.meta.port or 3491
--host <addr>	—	127.0.0.1
--brand <name>	DASHBOARD_BRAND	registry.meta.brand
--static-extra <dir>	—	(none — repeatable)

Programmatic

const { startDashboard } = require("@vraj0703/ai-dashboard");

await startDashboard({
  registry: "./registry.toml",        // path or already-parsed object
  port: 3491,
  staticExtras: ["./my-extra-pages"], // optional consumer-supplied pages
});

Registry format

[meta]
name    = "my-system"
brand   = "My System"
tagline = "Optional sub-header"
port    = 3491

[[organs]]
name = "service-a"
url  = "http://127.0.0.1:9001"
badge = "edge"          # optional, shown on the tile

[[organs]]
name = "service-b"
url  = "http://127.0.0.1:9002"
proxy_path = "/api/b"   # optional; defaults to /api/<name>

JSON works too — same shape, drop in .json instead of .toml.

The dashboard expects each organ to expose GET /health returning JSON with at least { status, version }. Anything beyond that is optional and ends up in details on the tile.

Stub default

The default organ client is StubOrganClient — it returns canned running responses for every organ in the registry. The dashboard runs out of the box even if nothing is listening on the configured URLs.

This is deliberate. New consumers see a working dashboard immediately; live wiring is a one-env-var swap:

DASHBOARD_USE_REAL_ORGAN_CLIENT=1 ai-dashboard --registry ./registry.toml
# or:
DASHBOARD_USE_REAL=all ai-dashboard --registry ./registry.toml

MCP tools

If you install the optional MCP peer deps:

npm install @modelcontextprotocol/sdk zod

You can mount the dashboard as an MCP server in your AI tool of choice:

const { createMcpServer, startStdio } = require("@vraj0703/ai-dashboard/mcp");
const { createContainer } = require("@vraj0703/ai-dashboard/container");
const { loadRegistryFile } = require("@vraj0703/ai-dashboard");

const container = createContainer({ registry: loadRegistryFile("./registry.toml") });
const server = createMcpServer({ container });
await startStdio(server);

Tool	Purpose
dashboard_health	Aggregate health of every organ in the registry
dashboard_organ_health	Health of a single named organ
dashboard_tail_events	Most recent N entries from the proxy network log
dashboard_meta	Brand + organ list (so an agent can discover what exists)

Custom pages

Drop your own HTML/CSS/JS into a directory and pass --static-extra <dir>. Files there are served before the bundled chrome — same filename overrides bundled assets:

ai-dashboard \
  --registry ./registry.toml \
  --static-extra ./my-pages

This is how raj-sadan keeps its principal-specific pages (chat, costs, brain, knowledge) without polluting the framework.

Architecture

Clean architecture: domain/ → data/ → presentation/ → di/. See ARCHITECTURE.md.

Single source of organ truth: the registry. Use cases never see organ names directly — they ask the client list(). Swap the client and the rest of the system follows.

Sibling packages

Repo	Role
ai-mind	Decision-making organ
ai-senses	Perception (WhatsApp, mobile, infra)
ai-memory	Vector + structured memory
ai-knowledge	Capability registry + Hebbian reinforcement
ai-constitution	Governance framework + minister templates
ai-architecture-renderer	SVG perspective renderer

Use the examples/raj-sadan/registry.toml shape to point a single dashboard at all six.

License

MIT.