Monitor

Under Development: The HORUS Monitor is under active development. Core monitoring features work (nodes, topics, graph, parameters, packages). Some functionality (remote deployment, recordings browser) is still being finalized.

The HORUS Monitor provides a real-time view of your running robot system through a web interface or terminal UI.

Quick Start

# Start your HORUS application
horus run

# In another terminal, start the monitor
horus monitor

Browser opens automatically to http://localhost:3000. On first run, you'll be prompted to set a password (or press Enter to skip).

# Custom port
horus monitor 8080

# Terminal UI mode (no browser needed)
horus monitor --tui

# Reset password
horus monitor --reset-password

Web Interface

The web monitor has 3 main tabs:

Monitor Tab

The main monitoring view with two sub-views:

List View — Shows nodes and topics in a grid layout:

• Nodes card: All running nodes with their status
• Topics card: Active message channels with sizes

Graph View — Interactive canvas showing:

• Nodes as circles connected to their topics
• Visual representation of the pub/sub network
• Helps answer "which nodes are talking to which topics?"

A status bar at the top always shows:

• Active Nodes count (hover for node list)
• Active Topics count (hover for topic list)
• Monitor port

Parameters Tab

Live runtime parameter editor:

• Search parameters by name
• Add new parameters at runtime
• Edit existing values (changes apply immediately)
• Delete parameters
• Export all parameters to file
• Import parameters from file

Useful for tuning PID gains, speed limits, sensor thresholds without restarting.

Packages Tab

Browse and manage HORUS packages:

• Search the registry
• Install packages
• Manage environments

Terminal UI Mode

For SSH sessions and headless servers:

horus monitor --tui

The TUI provides 8 tabs navigated with arrow keys:

Topic Debug Logging

In the Topics tab, press Enter on any topic to enable runtime debug logging. All send() and recv() calls on that topic will emit live log entries showing direction, IPC latency, and message summaries (if LogSummary is implemented). Press Esc to disable logging — zero overhead resumes immediately.

No code changes or recompilation required.

Network Access

The monitor binds to all network interfaces (0.0.0.0), so you can access it from:

• Same machine: http://localhost:3000
• Any device on the network: http://<your-ip>:3000

Always set a password when the monitor is network-accessible.

Security

The monitor supports password-based authentication for networked deployments.

Setup

On first run, set a password (or press Enter to skip authentication):

horus monitor

[SECURITY] HORUS Monitor - First Time Setup
Password: ********
Confirm password: ********
[SUCCESS] Password set successfully!

Reset password anytime:

horus monitor --reset-password

How Authentication Works

When a password is set:

1. The web UI shows a login page before granting access
2. All API endpoints require a valid session token (except /api/login)
3. Sessions expire after 1 hour of inactivity
4. Failed login attempts are rate-limited

When no password is set (Enter pressed at setup):

• All endpoints are accessible without authentication
• Suitable for local development only

API Authentication

# Login — returns a session token
curl -X POST http://localhost:3000/api/login \
  -H "Content-Type: application/json" \
  -d '{"password": "your_password"}'
# Returns: {"token": "abc123..."}

# Use token for API requests
curl http://localhost:3000/api/nodes \
  -H "Authorization: Bearer abc123..."

# Logout
curl -X POST http://localhost:3000/api/logout \
  -H "Authorization: Bearer abc123..."

Security Details

Password hash stored at ~/.horus/dashboard_password.hash.

For production deployments, consider placing a reverse proxy with TLS (e.g., nginx) in front of the monitor.

Recovery

If locked out:

# Option 1: Reset via CLI
horus monitor --reset-password

# Option 2: Delete the password hash file
rm ~/.horus/dashboard_password.hash
horus monitor  # Re-prompts for password setup

API Endpoints

The monitor exposes a REST API (authenticated when a password is set):

Common Scenarios

Debugging Message Flow

"My subscriber isn't getting messages"

1. Open Monitor tab, switch to Graph View
2. Is there an arrow from publisher -> topic -> subscriber?
3. If not: check topic name matches or node isn't running

"The robot is running slow"

1. Check nodes list for high CPU usage
2. Check tick rates — which node can't keep up?
3. Use logs endpoint to check for slow tick warnings

Live Parameter Tuning

Tuning PID controller:

1. Open Parameters tab
2. Search for pid
3. Edit pid.kp value — change applies instantly
4. Watch robot behavior, adjust until optimal
5. Export final values with Export button

Troubleshooting

Monitor shows nothing Make sure your HORUS application is running first (horus run).

Can't access from another device Check both devices are on the same network. Allow port through firewall: sudo ufw allow 3000.

Port already in use Specify a different port: horus monitor 8080.

Password reset Run horus monitor -r or delete ~/.horus/dashboard_password.hash.

Next Steps

• CLI Reference - Full CLI command reference
• Parameters Guide - Deep dive into runtime parameters