Tyto

A real-time Linux system monitoring dashboard with a modern web interface

Named after Tyto alba, the barn owl — nature's silent, watchful guardian

Features • Quick Start • Multi-Host Setup • API • Development

---

Overview

Tyto is a lightweight, containerized monitoring solution that provides real-time visibility into your Linux systems. Built with a Go backend for efficient metric collection and a SvelteKit frontend for a responsive, modern UI.

Key Highlights

• Real-time streaming via Server-Sent Events (SSE)
• Zero dependencies on the host system (runs in Docker)
• Multi-host support for monitoring multiple machines from one dashboard
• Desktop notifications for critical alerts
• Process management with kill/pause/resume functionality
• Dark/Light themes with responsive mobile design

---

Features

Category	Features
System	Hostname, kernel version, uptime, architecture
CPU	Per-core usage, frequency, load averages
Memory	RAM usage, buffers, cache, swap
Disk	Mount points, usage, I/O rates
Network	Interface stats, bandwidth rates, TCP connections
Processes	Top by CPU/Memory, detailed view, signal control
Temperature	Hardware sensors via hwmon
GPU	AMD GPU monitoring (utilization, VRAM, power, clocks)
Docker	Container stats (CPU, memory, status)
Systemd	Service status monitoring
Alerts	Configurable thresholds with desktop notifications
History	Sparkline charts for CPU, memory, network, disk I/O
Export	CSV and JSON export of current metrics

---

Quick Start

Using Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/yourusername/tyto.git
cd tyto

# Start the containers
docker compose up -d

# Access the dashboard
open http://localhost:9847

Ports

Service	Port	Description
Frontend	9847	Web dashboard
Backend	9848	API server (internal)

---

Configuration

Environment Variables

The backend container supports the following environment variables:

Variable	Default	Description
PORT	8080	Backend server port
PROC_PATH	/proc	Path to proc filesystem
SYS_PATH	/sys	Path to sys filesystem
MTAB_PATH	/etc/mtab	Path to mount table
DOCKER_SOCKET	/var/run/docker.sock	Docker socket path
DEFAULT_REFRESH_INTERVAL	5s	Default metric collection interval

Required Volume Mounts

For the backend to collect host metrics, these mounts are required:

volumes:
  - /proc:/host/proc:ro          # Process information
  - /sys:/host/sys:ro            # Hardware sensors, GPU info
  - /etc/mtab:/host/etc/mtab:ro  # Disk mount information

Optional Features

Docker Monitoring

Mount the Docker socket to enable container monitoring:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Systemd Service Monitoring

Mount the D-Bus socket to enable systemd service monitoring:

volumes:
  - /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro

---

Multi-Host Monitoring

System Monitor supports monitoring multiple hosts from a single dashboard. Each host runs its own backend container, and the frontend can switch between them.

Setting Up Remote Hosts

1. Deploy on each host you want to monitor:

# On remote-host-1 (e.g., 192.168.1.100)
docker compose up -d

2. Configure CORS (if accessing from a different origin):

The backend allows cross-origin requests by default. Ensure ports are accessible.

3. Add hosts in the dashboard:
   • Click the host selector dropdown in the header
   • Click "Add Remote Host"
   • Enter a name (e.g., "Web Server") and URL (e.g., http://192.168.1.100:9847)

Network Diagram

┌─────────────────────────────────────────────────────────────┐
│                      Your Browser                            │
│                   http://localhost:9847                      │
└──────────────────────────┬──────────────────────────────────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
            ▼              ▼              ▼
     ┌────────────┐ ┌────────────┐ ┌────────────┐
     │  Host A    │ │  Host B    │ │  Host C    │
     │ (local)    │ │ :9847      │ │ :9847      │
     │ Frontend + │ │ Frontend + │ │ Frontend + │
     │ Backend    │ │ Backend    │ │ Backend    │
     └────────────┘ └────────────┘ └────────────┘

Host Configuration Storage

Host configurations are stored in browser localStorage under the key tyto-hosts. The active host is stored in tyto-active-host.

---

API Reference

Endpoints

Method	Endpoint	Description
GET	/api/v1/stream	SSE stream of real-time metrics
GET	/api/v1/history	Historical metric data (1 hour)
GET	/api/v1/alerts	Current alerts and configuration
POST	/api/v1/alerts/config	Update alert thresholds
POST	/api/v1/alerts/:id/acknowledge	Acknowledge an alert
GET	/api/v1/processes/:pid	Detailed process information
POST	/api/v1/processes/:pid/signal	Send signal to process
POST	/api/v1/settings/refresh	Update refresh interval
GET	/api/v1/export/metrics?format=csv|json	Export current metrics
GET	/health	Health check endpoint

SSE Stream Format

The /api/v1/stream endpoint sends JSON messages with this structure:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "system": { "hostname": "...", "kernel": "...", "uptime": 12345 },
  "cpu": { "cores": [...], "totalUsage": 15.5, "loadAverage": {...} },
  "memory": { "total": 16000000000, "used": 8000000000, ... },
  "disk": { "mounts": [...], "io": [...] },
  "network": { "interfaces": [...], "connectionCount": 42 },
  "processes": { "topByCpu": [...], "topByMemory": [...], "total": 200 },
  "temperature": { "sensors": [...] },
  "gpu": { "available": true, "utilization": 45, ... },
  "docker": { "available": true, "containers": [...] },
  "systemd": { "available": true, "services": [...] }
}

Process Signal API

# Send SIGTERM (graceful termination)
curl -X POST http://localhost:9847/api/v1/processes/1234/signal \
  -H "Content-Type: application/json" \
  -d '{"signal": 15}'

# Send SIGKILL (force kill)
curl -X POST http://localhost:9847/api/v1/processes/1234/signal \
  -H "Content-Type: application/json" \
  -d '{"signal": 9}'

---

Development

Prerequisites

• Go 1.23+
• Node.js 22+
• Docker & Docker Compose (for containerized development)

Local Development

# Backend (Go)
cd backend
go mod download
go run ./cmd/server

# Frontend (SvelteKit)
cd frontend
npm install
npm run dev

Running Tests

# Backend tests
cd backend
go test ./...

# Frontend tests
cd frontend
npm test

Project Structure

tyto/
├── backend/
│   ├── cmd/server/          # Main entry point
│   ├── internal/
│   │   ├── api/             # HTTP handlers and routes
│   │   ├── alerts/          # Alert management
│   │   ├── collectors/      # Metric collectors
│   │   ├── config/          # Configuration
│   │   ├── history/         # Historical data storage
│   │   ├── models/          # Data structures
│   │   └── sse/             # Server-Sent Events broker
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── lib/
│   │   │   ├── api/         # API clients
│   │   │   ├── components/  # Svelte components
│   │   │   ├── stores/      # Svelte stores
│   │   │   ├── types/       # TypeScript types
│   │   │   └── utils/       # Utility functions
│   │   └── routes/          # SvelteKit routes
│   └── Dockerfile
└── docker-compose.yaml

Building Docker Images

# Build both images
docker compose build

# Build specific service
docker compose build backend
docker compose build frontend

---

Keyboard Shortcuts

Key	Action
T	Toggle dark/light theme
R	Cycle refresh rate
?	Show keyboard shortcuts
Esc	Close modals/panels

---

Alerts & Notifications

Configuring Thresholds

1. Open the Alerts card
2. Click "Configure Thresholds"
3. Set warning and critical percentages for each metric type
4. Click "Save Configuration"

Desktop Notifications

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

Note: Critical alerts require manual dismissal; warnings auto-close after 10 seconds.

---

Troubleshooting

No metrics displayed

1. Check if backend is running: docker compose ps
2. Verify volume mounts: docker inspect sysmon-backend
3. Check backend logs: docker compose logs backend

GPU not detected

AMD GPU monitoring requires:

• AMD GPU with amdgpu driver
• /sys/class/drm/card*/device/ accessible
• Proper volume mount: -v /sys:/host/sys:ro

Docker containers not showing

Ensure Docker socket is mounted:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Systemd services not showing

Mount D-Bus socket and ensure the container can access it:

volumes:
  - /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro

---

License

MIT License - see LICENSE for details.

---

Back to top