Skip to content

DASHBOARD_USAGE.md

Latest commit

 

History

History
333 lines (224 loc) · 6.19 KB

DASHBOARD_USAGE.md

File metadata and controls

333 lines (224 loc) · 6.19 KB
Error in user YAML: (<unknown>): mapping values are not allowed in this context at line 1 column 40
---
description: How to Start the Dashboard: **Multiple ways to start the Agent Coordination Dashboard** --- ## 🚀 Method 1: CLI Command (Easiest) # Default (localhost:8000) empa
---

How to Start the Dashboard

Multiple ways to start the Agent Coordination Dashboard

🚀 Method 1: CLI Command (Easiest)

# Default (localhost:8000)
empathy dashboard start

# Custom host/port
empathy dashboard start --host 0.0.0.0 --port 8080

# Get help
empathy dashboard start --help

When to use: Quick start, production deployments, CI/CD

📜 Method 2: Bash Script

cd /path/to/empathy-framework
./scripts/start_dashboard.sh

When to use: Development, testing, quick demos

🐍 Method 3: Python Import

from empathy_os.dashboard import run_standalone_dashboard

# Default settings
run_standalone_dashboard()

# Custom settings
run_standalone_dashboard(host="0.0.0.0", port=8080)

When to use: Embedding in your application, custom integration

📦 Method 4: Python Module

# Standalone version (direct Redis)
python -m empathy_os.dashboard.standalone_server

# Simple version (uses telemetry API)
python -m empathy_os.dashboard.simple_server

When to use: Testing different implementations, development

🔧 Method 5: Direct Execution

# From project root
python -c "from empathy_os.dashboard import run_standalone_dashboard; run_standalone_dashboard()"

# With custom port
python -c "from empathy_os.dashboard import run_standalone_dashboard; run_standalone_dashboard(port=8080)"

When to use: One-liners, automation scripts

📊 Before Starting: Populate Test Data

The dashboard needs data in Redis to display. Populate it with:

python scripts/populate_redis_direct.py

This creates:

  • 5 active agents with heartbeats
  • 10 coordination signals
  • 15 event stream entries
  • 2 pending approval requests
  • 333 quality feedback samples

🌐 Accessing the Dashboard

Once started, open your browser to:

http://localhost:8000

Or if you changed the host/port:

http://{your-host}:{your-port}

📋 Complete Usage Examples

Example 1: Quick Start for Testing

# Terminal 1: Populate data
cd /path/to/empathy-framework
python scripts/populate_redis_direct.py

# Terminal 2: Start dashboard
empathy dashboard start

# Open browser to http://localhost:8000

Example 2: Production Deployment

# Bind to all interfaces on port 8080
empathy dashboard start --host 0.0.0.0 --port 8080

# Or with nohup for background
nohup empathy dashboard start --host 0.0.0.0 --port 8080 > dashboard.log 2>&1 &

Example 3: Development with Auto-Reload

# Use script for quick restarts
./scripts/start_dashboard.sh

# Ctrl+C to stop, then restart to see changes

Example 4: Custom Integration

# In your Python application
from empathy_os.dashboard import run_standalone_dashboard
import threading

# Run dashboard in background thread
dashboard_thread = threading.Thread(
    target=run_standalone_dashboard,
    kwargs={"host": "127.0.0.1", "port": 8000"},
    daemon=True
)
dashboard_thread.start()

# Your application continues
print("Dashboard running in background")
# ... rest of your code

Example 5: Docker Container

FROM python:3.10-slim

WORKDIR /app
COPY . .

RUN pip install -e .
RUN pip install redis

EXPOSE 8000

CMD ["empathy", "dashboard", "start", "--host", "0.0.0.0", "--port", "8000"]
# Build and run
docker build -t empathy-dashboard .
docker run -p 8000:8000 empathy-dashboard

⚙️ Configuration Options

Host Options

# Localhost only (secure, default)
empathy dashboard start --host 127.0.0.1

# All interfaces (accessible from network)
empathy dashboard start --host 0.0.0.0

# Specific IP
empathy dashboard start --host 192.168.1.100

Port Options

# Default port
empathy dashboard start --port 8000

# Alternative ports
empathy dashboard start --port 8080
empathy dashboard start --port 3000
empathy dashboard start --port 80  # Requires sudo

🔄 Auto-Refresh Behavior

The dashboard automatically refreshes every 5 seconds:

  • Fetches latest data from Redis
  • Updates all 7 panels
  • Shows "Last update: [timestamp]" at bottom

No manual refresh needed! Just watch the data update in real-time.

🛑 Stopping the Dashboard

Keyboard interrupt:

Press Ctrl+C

Kill process:

# Find process
lsof -i :8000

# Kill it
kill <PID>

Docker:

docker stop <container-id>

🐛 Troubleshooting

Port Already in Use

Error: Address already in use

Solution:

# Find what's using port 8000
lsof -i :8000

# Kill it or use different port
empathy dashboard start --port 8080

Dashboard Shows No Data

Cause: Redis is empty or data expired

Solution:

python scripts/populate_redis_direct.py

Cannot Connect to Redis

Error: Connection refused

Solution:

# Start Redis
redis-server

# Or via empathy CLI
empathy memory start

Permission Denied (Port 80)

Error: Permission denied

Solution:

# Use port > 1024 (doesn't require sudo)
empathy dashboard start --port 8080

# Or use sudo (not recommended)
sudo empathy dashboard start --port 80

📚 Related Documentation

✅ Quick Reference

Method Command When to Use
CLI empathy dashboard start Production, recommended
Script ./scripts/start_dashboard.sh Development, testing
Python run_standalone_dashboard() Integration, custom apps
Module python -m empathy_os.dashboard.standalone_server Direct execution

Default URL: http://localhost:8000

Auto-refresh: Every 5 seconds

Stop: Press Ctrl+C

Version: 1.0.0 Last Updated: January 27, 2026 Status: Production Ready ✅