NerveCenter Documentation

The real-time monitoring dashboard for AI agents. Think Datadog for AI — open-source, self-hosted, framework agnostic.

Overview

NerveCenter gives you full visibility into your AI agent fleet. Whether you're running a single agent or an entire team of specialized AI workers, NerveCenter provides:

• Real-time agent status — online, idle, offline at a glance
• Token usage tracking — monitor consumption and costs across all agents
• Heartbeat monitoring — know instantly when an agent goes dark
• Live output streaming — watch agent responses and tool calls in real time
• Memory inspection — debug context and memory issues
• Activity feed — unified timeline of all agent events
• Session history — full audit trail with replay

Installation

Prerequisites

• Node.js 18+ (recommended: 20 LTS)
• npm or yarn

Install via npm

npm install -g openclaw

This installs the OpenClaw CLI which includes NerveCenter as a built-in module.

Verify installation

openclaw --version
openclaw nervecenter status

Quick Start

Get NerveCenter running in under 2 minutes:

# 1. Install OpenClaw
npm install -g openclaw

# 2. Initialize a config
openclaw init

# 3. Start NerveCenter
openclaw nervecenter start

# 4. Open the dashboard
open http://localhost:3000

Configuration File

NerveCenter is configured via a YAML file at ~/.openclaw/nervecenter.yaml (or specify with --config).

# nervecenter.yaml

server:
  port: 3000
  host: 0.0.0.0

monitoring:
  heartbeat_interval: 30s    # How often to check agent health
  grace_period: 90s           # Time before marking agent as offline
  token_tracking: true        # Enable token usage monitoring
  history_retention: 30d      # How long to keep session history

dashboard:
  theme: dark                 # dark | light
  refresh_rate: 2s            # Dashboard auto-refresh interval
  show_token_costs: true      # Show estimated costs

agents:
  - name: titan
    endpoint: http://localhost:8880
    role: orchestrator
    tags: [core, management]

  - name: forge
    endpoint: http://localhost:8881
    role: backend
    tags: [engineering]

  - name: pixel
    endpoint: http://localhost:8882
    role: frontend
    tags: [engineering, ui]

Agent Setup

Each agent in your fleet needs a minimal configuration entry. Here's the full schema:

agents:
  - name: my-agent            # Required: unique identifier
    endpoint: http://host:port # Required: agent's HTTP endpoint
    role: backend              # Optional: display role in dashboard
    tags: [team-a, critical]   # Optional: for filtering/grouping
    heartbeat_path: /health    # Optional: custom health check path
    timeout: 5s                # Optional: health check timeout
    metadata:                  # Optional: custom key-value pairs
      owner: alice
      version: "2.1"

Agent Discovery

If your agents are connected to an OpenClaw gateway, NerveCenter can auto-discover them. Enable this with:

discovery:
  gateway: http://localhost:8888
  auto_register: true
  poll_interval: 10s

Environment Variables

All config options can be overridden via environment variables:

NC_PORT=3000                    # Server port
NC_HOST=0.0.0.0                 # Bind address
NC_HEARTBEAT_INTERVAL=30        # Seconds between health checks
NC_GRACE_PERIOD=90              # Seconds before offline status
NC_TOKEN_TRACKING=true          # Enable token tracking
NC_HISTORY_RETENTION=30         # Days to retain history
NC_GATEWAY_URL=http://localhost:8888  # OpenClaw gateway URL

Dashboard

The NerveCenter dashboard provides a real-time view of your agent fleet. Key panels include:

Agent List

Shows all registered agents with their current status (online/idle/offline), role, and last heartbeat time. Click any agent to see detailed metrics.

Token Usage

Tracks input and output tokens per agent over configurable time windows (1h, 24h, 7d, 30d). Includes cost estimates based on model pricing.

Live Output

Streams agent output in real time. Filter by agent, event type, or search for specific content. Supports auto-scroll and pause.

Memory Viewer

Inspect the current memory/context state of any agent. Useful for debugging context window issues, checking what agents "remember," and optimizing memory strategies.

Monitoring

NerveCenter continuously monitors your agents via configurable health checks:

• Heartbeat — periodic HTTP pings to each agent's health endpoint
• Token metering — tracks API usage per agent per session
• Error tracking — captures and categorizes agent errors
• Latency monitoring — measures response times over time

Status States

online   → Agent responded within the last heartbeat interval
idle     → Agent is connected but no activity in the last 5 minutes
offline  → Agent failed to respond within the grace period
error    → Agent responded with an error status

Alerts

Configure alerts to get notified when agents need attention:

alerts:
  channels:
    - type: webhook
      url: https://hooks.slack.com/services/...
    - type: telegram
      chat_id: "123456789"
      bot_token: $TELEGRAM_BOT_TOKEN

  rules:
    - event: agent_offline
      severity: critical
      notify: [webhook, telegram]
    - event: token_budget_exceeded
      threshold: 100000
      severity: warning
      notify: [webhook]

FAQ

Does NerveCenter work with non-OpenClaw agents?

Yes. Any agent that exposes an HTTP health endpoint can be monitored. You just need to configure the agent entry manually in your config file. NerveCenter is framework agnostic.

How much overhead does monitoring add?

Minimal. Health checks are lightweight HTTP pings (typically <1ms). Token tracking piggybacks on existing API responses. The dashboard itself consumes negligible resources.

Can I run NerveCenter in Docker?

Yes. A Docker image is available:

docker run -d \
  -p 3000:3000 \
  -v ~/.openclaw:/root/.openclaw \
  ghcr.io/alghanim/nervecenter:latest

Is there a cloud-hosted version?

Not yet. NerveCenter is designed to be self-hosted. A managed cloud version is on the roadmap.

How do I contribute?

NerveCenter is open source! Check out the GitHub repository, open issues, or submit pull requests. All contributions are welcome.