tyto/docs/usage.md

Usage Guide

This guide covers all features of the Tyto dashboard.

Dashboard Overview

The main dashboard displays real-time system metrics in a card-based layout. Each card can be expanded for more details.

Navigation

Element	Description
Header	Host selector, refresh rate, theme toggle, user menu
Cards	Metric categories (CPU, Memory, Disk, etc.)
Sparklines	Historical trends for key metrics

Keyboard Shortcuts

Key	Action
T	Toggle dark/light theme
R	Cycle refresh rate (1s → 5s → 10s → 30s)
?	Show keyboard shortcuts help
Esc	Close modals and panels

Metric Cards

System Information

Displays basic system information:

• Hostname: System hostname
• Kernel: Linux kernel version
• Uptime: Time since last boot
• Architecture: CPU architecture (x86_64, arm64, etc.)

CPU

Shows processor utilization:

• Total Usage: Overall CPU usage percentage
• Per-Core: Individual core utilization bars
• Load Average: 1, 5, and 15-minute load averages
• Frequency: Current and max CPU frequency

Sparkline: Shows CPU usage trend over the last hour.

Memory

Displays RAM and swap usage:

• Used / Total: Current memory consumption
• Buffers: Kernel buffer cache
• Cached: Page cache
• Available: Memory available for applications
• Swap: Swap usage if enabled

Sparkline: Shows memory usage trend.

Disk

Shows storage information:

• Mount Points: Each mounted filesystem
• Usage Bar: Visual usage indicator
• Size: Used and total space
• I/O Rates: Read/write speeds (MB/s)

Sparkline: Shows disk I/O trend.

Network

Displays network interface statistics:

• Interfaces: Each network interface (eth0, wlan0, etc.)
• IP Address: IPv4 and IPv6 addresses
• Bandwidth: Current upload/download rates
• Total Traffic: Cumulative bytes transferred
• Connections: Active TCP connection count

Sparkline: Shows bandwidth trend.

Processes

Lists top processes by resource usage:

• By CPU: Processes consuming most CPU
• By Memory: Processes using most RAM
• Total Count: Number of running processes

Click a process to see details:

• Full command line
• User and group
• State and priority
• Open files and threads

Process Control:

• Terminate (SIGTERM): Graceful shutdown
• Kill (SIGKILL): Force kill
• Pause (SIGSTOP): Suspend process
• Resume (SIGCONT): Continue paused process

Temperature

Shows hardware sensor readings:

• CPU Temperature: Core temperatures
• GPU Temperature: Graphics card (if available)
• Disk Temperature: NVMe/SATA sensors
• Other Sensors: Motherboard, ambient, etc.

GPU

Displays graphics card metrics (if detected):

• Utilization: GPU compute usage
• VRAM: Video memory usage
• Temperature: GPU temperature
• Power: Current power consumption
• Clocks: Core and memory frequencies

Supports: NVIDIA, AMD, and Intel GPUs.

Docker

Lists running containers (requires Docker socket mount):

• Container Name: Container identifier
• Image: Base image
• Status: Running, paused, stopped
• CPU/Memory: Resource usage per container

Systemd

Shows system service status (requires D-Bus socket mount):

• Service Name: Unit name
• State: Active, inactive, failed
• Sub-state: Running, exited, dead

Alerts & Notifications

Configuring Thresholds

1. Click the Alerts card header
2. Click Configure Thresholds
3. Set levels for each metric:

Metric	Warning	Critical
CPU	80%	95%
Memory	85%	95%
Disk	80%	90%

4. Click Save Configuration

Alert States

State	Description
Normal	Below warning threshold
Warning	Above warning, below critical
Critical	Above critical threshold

Desktop Notifications

1. Enable Desktop Notifications toggle in Alerts card
2. Allow browser notification permission when prompted
3. Notifications appear for new warning/critical alerts

Behavior:

• Warning alerts auto-dismiss after 10 seconds
• Critical alerts require manual acknowledgment
• Click notification to jump to affected metric

Acknowledging Alerts

1. Click the alert in the Alerts card
2. Click Acknowledge
3. Alert moves to "Acknowledged" section

Log Viewer

Access at /logs in the dashboard.

Filtering Logs

Filter	Description
Search	Full-text search in messages
Level	Filter by severity (debug, info, warning, error, fatal)
Source	Filter by source type (journal, file, docker)
Agent	Filter by agent ID (multi-device mode)

Live Mode

Click Go Live to stream logs in real-time. New entries appear at the top.

Log Sources

Source	Description
Systemd Journal	System and service logs
File	Tailed log files
Docker	Container stdout/stderr

Data Export

Exporting Metrics

1. Click the Export button in the header
2. Choose format:
   • CSV: Spreadsheet-compatible
   • JSON: Machine-readable
3. File downloads with current timestamp

API Export

# CSV export
curl http://localhost:8080/api/v1/export/metrics?format=csv -o metrics.csv

# JSON export
curl http://localhost:8080/api/v1/export/metrics?format=json -o metrics.json

Theme & Display

Dark/Light Mode

Toggle with:

• T keyboard shortcut
• Theme toggle button in header

Theme preference is saved in browser localStorage.

Responsive Design

The dashboard adapts to screen size:

• Desktop: Full card grid
• Tablet: Reduced columns
• Mobile: Single column, simplified charts

Multi-Host Switching

In standalone mode with multiple hosts configured:

1. Click the host selector dropdown in the header
2. Select a host or click Add Remote Host
3. Enter host name and URL
4. Dashboard switches to selected host

Host configurations are stored in browser localStorage.

Performance Tips

Reduce Bandwidth

• Increase refresh rate (R key) to 10s or 30s
• Disable sparkline history if not needed

Reduce Server Load

• Limit visible cards
• Use longer refresh intervals
• Disable log streaming when not needed

Browser Performance

• Close unused tabs
• Disable desktop notifications if not needed
• Use production builds (not development mode)