tyto/README.md

# Tyto

<div align="center">

![Go Version](https://img.shields.io/badge/Go-1.23-00ADD8?style=flat-square&logo=go)
![SvelteKit](https://img.shields.io/badge/SvelteKit-2.0-FF3E00?style=flat-square&logo=svelte)
![Tailwind CSS](https://img.shields.io/badge/Tailwind-3.4-06B6D4?style=flat-square&logo=tailwindcss)
![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=flat-square&logo=docker)
![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)

**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)

</div>

---

## 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

<details>
<summary><b>Docker Monitoring</b></summary>

Mount the Docker socket to enable container monitoring:

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

</details>

<details>
<summary><b>Systemd Service Monitoring</b></summary>

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

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

</details>

---

## 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

<details>
<summary><b>No metrics displayed</b></summary>

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`

</details>

<details>
<summary><b>GPU not detected</b></summary>

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

</details>

<details>
<summary><b>Docker containers not showing</b></summary>

Ensure Docker socket is mounted:
```yaml
volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro
```

</details>

<details>
<summary><b>Systemd services not showing</b></summary>

Mount D-Bus socket and ensure the container can access it:
```yaml
volumes:
  - /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro
```

</details>

---

## License

MIT License - see [LICENSE](LICENSE) for details.

---

<div align="center">

**[Back to top](#tyto)**

</div>