# 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](#features) • [Quick Start](#quick-start) • [Multi-Host Setup](#multi-host-monitoring) • [API](#api-reference) • [Development](#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)
```bash
# 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:
```yaml
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:
```yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
```
Systemd Service Monitoring
Mount the D-Bus socket to enable systemd service monitoring:
```yaml
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:
```bash
# 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:
```json
{
"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
```bash
# 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
```bash
# Backend (Go)
cd backend
go mod download
go run ./cmd/server
# Frontend (SvelteKit)
cd frontend
npm install
npm run dev
```
### Running Tests
```bash
# 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
```bash
# 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:
```yaml
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:
```yaml
volumes:
- /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro
```
---
## License
MIT License - see [LICENSE](LICENSE) for details.
---
**[Back to top](#tyto)**