Agent Relay Dashboard

Web dashboard for Agent Relay - real-time agent monitoring, communication, and fleet management.

Works out-of-the-box - sensible defaults, no configuration required. Can also run standalone with mock data for testing and demos.

Quick Start

# Install
npm install
# Run in standalone mode (no dependencies required)
npm run dev:mock
# Or run connected to relay daemon
npm run dev

Architecture

The dashboard supports three operation modes:

1. Full Mode (CLI Integration)

Used by agent-relay up --dashboard. Direct @agent-relay package integration.

┌─────────────────────────────────────────────────┐
│ Dashboard (Full Mode) │
│ ┌──────────────────────────────────────────┐ │
│ │ Next.js Frontend │ │
│ │ React Components • Hooks • API Client │ │
│ └────────────────┬─────────────────────────┘ │
│ │ │
│ ┌────────────────▼─────────────────────────┐ │
│ │ Full Server (startDashboard) │ │
│ │ @agent-relay/storage • sdk • bridge │ │
│ │ Direct DB access • Agent spawning │ │
│ └──────────────────────────────────────────┘ │
│ Port 3888 │
└─────────────────────────────────────────────────┘

2. Proxy Mode (Standalone)

Forwards requests to a running relay daemon.

┌─────────────────────┐ ┌─────────────────────┐
│ Dashboard │ │ Relay Daemon │
│ ┌──────────────┐ │ │ │
│ │ Next.js UI │ │ │ ┌─────────────┐ │
│ └───────┬──────┘ │ │ │ Agents │ │
│ │ │ │ │ Storage │ │
│ ┌───────▼──────┐ │ │ │ Bridge │ │
│ │ Proxy Server │───┼─────┼─▶ └─────────────┘ │
│ └──────────────┘ │ │ │
│ Port 3888 │ │ Port 3889 │
└─────────────────────┘ └─────────────────────┘

3. Mock Mode (Development)

Returns fixture data. No external dependencies required.

┌─────────────────────────────────────────────────┐
│ Dashboard (Mock Mode) │
│ ┌──────────────────────────────────────────┐ │
│ │ Next.js Frontend │ │
│ │ React Components • Hooks • API Client │ │
│ └────────────────┬─────────────────────────┘ │
│ │ │
│ ┌────────────────▼─────────────────────────┐ │
│ │ Express Server (Mock Mode) │ │
│ │ Returns fixture data • No deps needed │ │
│ └──────────────────────────────────────────┘ │
│ Port 3888 │
└─────────────────────────────────────────────────┘

Installation

# Install globally
npm install -g @agent-relay/dashboard
# Or use npx
npx @agent-relay/dashboard

Usage

Standalone Mode (No Dependencies)

Perfect for development, testing, and demos:

# Using npm scripts
npm run dev:mock # Development with hot reload
npm run start:mock # Production build# Using CLI
relay-dashboard --mock
relay-dashboard -m -v # Mock mode with verbose logging

Connected to Relay Daemon

# Start relay daemon first
agent-relay up
# Then start dashboard
relay-dashboard
npm run dev

CLI Options

relay-dashboard [options]
Options:
-p, --port <port> Port to listen on (default: 3888)
-r, --relay-url <url> Relay daemon URL (default: http://localhost:3889)
-s, --static-dir <path> Static files directory (default: ./out)
-m, --mock Run in mock mode - no relay daemon required
-v, --verbose Enable verbose logging
-h, --help Show help
Examples:
relay-dashboard # Proxy mode
relay-dashboard --mock # Standalone with mock data
relay-dashboard -m -v # Mock mode, verbose
relay-dashboard -p 4000 -m # Custom port

Environment Variables

All environment variables are optional - sensible defaults work out-of-the-box.

Variable	Default	Description
PORT	3888	Dashboard server port
RELAY_URL	http://localhost:3889	Relay daemon URL
STATIC_DIR	./out	Static files directory
MOCK	false	Enable mock mode
VERBOSE	false	Enable verbose logging
CORS_ORIGINS	(none)	Allowed CORS origins (comma-separated, or *)
REQUEST_TIMEOUT	30000	Request timeout in milliseconds

Development

# Install dependencies
npm install
# Development (proxy mode - needs relay daemon)
npm run dev
# Development (mock mode - standalone)
npm run dev:mock
# Build
npm run build
# Run tests
npm test# Type checking
npm run typecheck
# Test coverage
npm run test:coverage

Project Structure

This is a monorepo with two packages:

relay-dashboard/
├── packages/
│ ├── dashboard/ # @agent-relay/dashboard
│ │ ├── src/
│ │ │ ├── app/ # Next.js App Router pages
│ │ │ ├── components/ # React components
│ │ │ │ └── hooks/ # Custom React hooks
│ │ │ ├── lib/ # API clients & utilities
│ │ │ └── types/ # TypeScript definitions
│ │ ├── public/ # Static assets
│ │ ├── out/ # Built static site
│ │ └── index.ts # Re-exports from dashboard-server
│ │
│ └── dashboard-server/ # @agent-relay/dashboard-server
│ └── src/
│ ├── server.ts # Main server with @agent-relay integrations (5,900+ lines)
│ ├── proxy-server.ts # Lightweight proxy/mock server for development
│ ├── index.ts # Package exports
│ ├── start.ts # CLI entry point
│ ├── services/ # Business logic modules
│ │ ├── metrics.ts
│ │ ├── needs-attention.ts
│ │ ├── user-bridge.ts
│ │ └── health-worker-manager.ts
│ ├── types/ # TypeScript type definitions
│ └── mocks/ # Mock data for standalone mode
│ ├── fixtures.ts
│ └── routes.ts
│
├── package.json # Root workspace config
└── README.md

Testing

The dashboard includes comprehensive tests:

# Run all tests
npm test# Watch mode
npm run test:watch
# Coverage report
npm run test:coverage

Test Categories

• Server Tests - Mock mode, proxy mode, health checks
• Fixture Tests - Validates mock data structure
• Component Tests - React component tests

Mock Data

Mock mode includes realistic fixture data for:

• Agents - Multiple agents with different statuses
• Messages - Sample message threads
• Sessions - Active and historical sessions
• Channels - Team communication channels
• Decisions - Pending approval/choice decisions
• Tasks - Task assignments with various states
• Fleet - Multi-server fleet statistics
• Metrics - System and agent metrics

All fixtures are in packages/dashboard-server/mocks/fixtures.ts and can be customized.

API Endpoints

In Mock Mode

Returns fixture data for all endpoints:

Endpoint	Description
GET /api/data	Dashboard data (agents, messages, sessions)
GET /api/agents/:name/online	Agent online status
POST /api/spawn	Spawn agent (mock)
POST /api/send	Send message (mock)
GET /api/channels	List channels
GET /api/decisions	List pending decisions
GET /api/tasks	List tasks
GET /api/metrics	System metrics
GET /api/fleet/stats	Fleet statistics
WS /ws	WebSocket (sends periodic mock updates)

In Proxy Mode

Forwards to relay daemon at configured URL.

Deployment

Fly.io

fly apps create relay-dashboard
fly secrets set RELAY_URL=https://your-relay.fly.dev
fly deploy

Docker

docker build -t relay-dashboard .# Mock mode
docker run -p 3888:3888 -e MOCK=true relay-dashboard
# Proxy mode
docker run -p 3888:3888 -e RELAY_URL=http://relay:3889 relay-dashboard

Static Hosting

Export to out/ and deploy to any static host. Configure reverse proxy for /api/* and /ws.

Features

• Real-time monitoring - Live agent status, messages, and activity via WebSocket
• Fleet management - Multi-project/workspace support with Bridge view
• Communication - Channels, direct messages, broadcasts, @mentions
• Terminal logs - Stream live PTY output from agents
• Decision queue - Approve/reject agent decisions requiring human input
• Metrics - System health, throughput, session lifecycle
• Theming - Light/dark mode, compact display options

License

Apache-2.0 - Copyright 2025 Agent Workforce Incorporated