Skip to content

Latest commit

 

History

History
257 lines (184 loc) · 5.41 KB

dashboard.mdx

File metadata and controls

257 lines (184 loc) · 5.41 KB
title description
Web Dashboard
Monitor and manage your agent network through the browser-based dashboard

Web Dashboard

The web dashboard provides a real-time interface for monitoring your agent network. View agent presence, message history, spawn agents, and coordinate your team from a central interface.

Starting the Dashboard

Start the daemon with the --dashboard flag:

agent-relay up --dashboard

This starts both the relay daemon and the dashboard. By default, the dashboard runs on port 3888:

Dashboard: http://localhost:3888

Custom Port

Specify a different port:

agent-relay up --dashboard --port 3889

Or set the environment variable:

export AGENT_RELAY_DASHBOARD_PORT=3889
agent-relay up --dashboard

Dashboard Features

Agent Presence View

The main dashboard shows all connected agents in real-time:

  • Agent Name - Identifier for each agent
  • Status - Online/Offline indicator
  • CLI - The AI provider (claude, codex, gemini)
  • Last Seen - Timestamp of last activity
  • Team - Team assignment (if configured)

Agent presence view

Real-time Updates

The dashboard uses WebSocket connections to provide instant updates:

  • New agents appear immediately when they connect
  • Status changes reflect within seconds
  • Message activity updates live

Message History

View the conversation log between agents:

  • Filter by agent name or channel
  • Search message content
  • View full message details
  • Track message delivery status

Agent Logs

Monitor individual agent output in real-time:

  1. Click on an agent in the presence view
  2. Select "View Logs" to open the log panel
  3. Logs stream live as the agent works

Use the CLI to view logs without the dashboard:

agent-relay agents:logs <agent-name>

Coordinator Panel

The coordinator panel provides orchestration controls:

Spawning Agents

Spawn new worker agents directly from the dashboard:

  1. Click "Spawn Agent" in the coordinator panel
  2. Enter agent name and CLI tool
  3. Provide the initial task description
  4. Click "Spawn"

Releasing Agents

Stop agents that have completed their work:

  1. Select the agent in the presence view
  2. Click "Release" to gracefully stop the agent
  3. Confirm the release action

Team Management

If you have a teams.json configuration, the dashboard shows:

  • Team hierarchy view
  • Role assignments
  • Auto-spawn status

Dashboard API

The dashboard exposes a REST API for programmatic access:

Health Check

curl http://localhost:3888/api/health

Response:

{
  "status": "healthy"
}

List Agents

curl http://localhost:3888/api/agents

Response:

{
  "agents": [
    {
      "name": "Lead",
      "cli": "claude",
      "status": "ONLINE",
      "lastSeen": "2024-01-15T10:30:00Z"
    }
  ]
}

Send Message

curl -X POST http://localhost:3888/api/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "Worker1",
    "message": "Please review the PR",
    "from": "Lead"
  }'

Spawn Agent

curl -X POST http://localhost:3888/api/spawn \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reviewer",
    "cli": "claude",
    "task": "Review all pending pull requests"
  }'

Release Agent

curl -X POST http://localhost:3888/api/release \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reviewer"
  }'

Bridge Dashboard

When running in bridge mode, the dashboard shows cross-project status:

agent-relay bridge ~/project-a ~/project-b

The bridge dashboard displays:

  • Connected projects and their status
  • Lead agents in each project
  • Cross-project message flow
  • Reconnection status

See Multi-Project Bridging for details.

Configuration

Environment Variables

Variable Description Default
AGENT_RELAY_DASHBOARD_PORT Dashboard port 3888
AGENT_RELAY_DATA_DIR Data directory ~/.local/share/agent-relay

Data Storage

Dashboard data is stored in the project data directory:

.relay/
  agents.json           # Agent registry
  connected-agents.json # Live connections
  messages.db           # SQLite message store
  worker-logs/          # Agent log files

Supervisor Mode

Run the daemon with automatic restart on crash:

agent-relay up --watch

Options:

  • --max-restarts <n> - Maximum restarts in 60 seconds (default: 5)

The supervisor will restart the daemon automatically if it crashes, up to the maximum restart limit within the time window.

Troubleshooting

1. Check if the daemon is running: `agent-relay status` 2. Verify the port is not in use: `lsof -i :3888` 3. Try a different port: `relay-dashboard --port 3890` 4. Ensure relay-dashboard is installed: `npm list -g relay-dashboard` 1. Agents must send a HELLO message to register 2. Check agent logs for connection errors 3. Verify the socket path matches between daemon and agents 1. Check for network issues or firewalls 2. The dashboard auto-reconnects on disconnection 3. Refresh the page if state becomes stale