Tyto

A real-time Linux system monitoring dashboard with multi-device support

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

Quick Start • Features • Usage • Multi-Device • Security • API • Deployment • 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-device support with lightweight agents and mTLS security
• Desktop notifications for critical alerts
• Process management with kill/pause/resume functionality
• Dark/Light themes with responsive mobile design

---

Quick Start

Standalone Mode (Single Host)

The simplest way to monitor a single machine:

git clone https://somegit.dev/vikingowl/tyto.git
cd tyto
docker compose up -d

# Access dashboard at http://localhost:3000

Server Mode (Multi-Device)

For monitoring multiple hosts from a central dashboard:

# On the central server
TYTO_MODE=server docker compose up -d

# Then deploy agents on each host (see Multi-Device Setup)

One-Line Install (Linux)

curl -fsSL https://somegit.dev/vikingowl/tyto/raw/branch/main/scripts/install.sh | sudo bash

Ports

Service	Port	Description
Frontend	3000	Web dashboard
Backend	8080	HTTP API
gRPC	9849	Agent connections (server mode)

---

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	Multi-vendor: NVIDIA, AMD, Intel (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
Logs	Centralized log collection from journal, files, Docker
Auth	Local accounts and LDAP/AD integration
RBAC	Role-based access control with customizable permissions

---

Usage

Dashboard

The main dashboard displays real-time metrics in card format. Click any card to expand details.

Keyboard Shortcuts

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

Alerts & Notifications

Configure thresholds:

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

Enable desktop notifications:

1. Toggle "Desktop Notifications" in the Alerts card
2. Allow browser notification permission when prompted

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

Log Viewer

Access the log viewer at /logs to search and filter logs from all monitored hosts.

Supported sources:

Source	Description
Systemd Journal	System and service logs via journalctl
File	Tail log files with format parsing
Docker	Container stdout/stderr logs

Query parameters:

Parameter	Description
agent_id	Filter by agent
source	Filter by source type (journal, file, docker)
level	Comma-separated levels (debug, info, warning, error, fatal)
q	Full-text search in message
from, to	Time range (ISO 8601)

---

Configuration

Operational Modes

Mode	Description
standalone	Single-host monitoring, no database (default)
server	Central server for multi-device with database
agent	Lightweight agent reporting to central server

TYTO_MODE=server tyto

Environment Variables

Variable	Default	Description
TYTO_MODE	standalone	Operational mode
TYTO_REFRESH_RATE	5	Collection interval (seconds)
TYTO_LOG_LEVEL	info	Log level (debug, info, warn, error)
TYTO_DB_TYPE	sqlite	Database type (sqlite, postgres)
TYTO_DB_PATH	/data/tyto.db	SQLite database path
TYTO_DB_URL		PostgreSQL connection string

Database

SQLite (default):

database:
  type: sqlite
  path: /var/lib/tyto/tyto.db

PostgreSQL:

database:
  type: postgres
  url: postgres://user:pass@localhost:5432/tyto?sslmode=require

Data Retention

database:
  retention:
    raw: 24h           # Full resolution
    one_minute: 168h   # 7 days
    five_minute: 720h  # 30 days
    hourly: 8760h      # 1 year
    logs: 168h         # 7 days

Volume Mounts

Required for host metrics:

volumes:
  - /proc:/host/proc:ro
  - /sys:/host/sys:ro
  - /etc/mtab:/host/etc/mtab:ro

Optional: Docker monitoring

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

Optional: Systemd monitoring

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

---

Multi-Device Setup

Monitor multiple hosts from a single dashboard using lightweight agents.

Architecture

                        ┌─────────────────┐
                        │    Browser      │
                        │  (Dashboard)    │
                        └────────┬────────┘
                                 │ SSE/HTTP
                                 ▼
┌────────────────────────────────────────────────────────────────┐
│                      Central Server                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  HTTP API    │  │  SSE Broker  │  │   gRPC Hub (mTLS)    │  │
│  │  :8080       │  │  (metrics)   │  │   :9849              │  │
│  └──────────────┘  └──────────────┘  └──────────┬───────────┘  │
│  ┌──────────────┐  ┌──────────────┐             │              │
│  │  Database    │  │   Registry   │             │              │
│  │  (SQLite/PG) │  │   (agents)   │             │              │
│  └──────────────┘  └──────────────┘             │              │
└─────────────────────────────────────────────────┼──────────────┘
                                                  │
              ┌───────────────────────────────────┼───────────────────────────┐
              │                                   │                           │
              ▼                                   ▼                           ▼
     ┌───────────────┐                   ┌───────────────┐           ┌───────────────┐
     │  Agent        │                   │  Agent        │           │  Agent        │
     │  (web-01)     │                   │  (db-01)      │           │  (app-01)     │
     │  Linux/x64    │                   │  Linux/ARM64  │           │  Linux/x64    │
     └───────────────┘                   └───────────────┘           └───────────────┘

1. Set Up the Server

# Start server with database
TYTO_MODE=server docker compose up -d

2. Initialize PKI (mTLS)

# Create Certificate Authority
tyto pki init-ca --cn "Tyto CA" --out /etc/tyto/pki/

# Generate server certificate
tyto pki gen-server --ca-dir /etc/tyto/pki/ --dns tyto.example.com

# Generate agent certificates
tyto pki gen-agent --ca-dir /etc/tyto/pki/ --agent-id web-server-01
tyto pki gen-agent --ca-dir /etc/tyto/pki/ --agent-id db-server-01

3. Deploy Agents

Install on each monitored host:

curl -fsSL https://somegit.dev/vikingowl/tyto/raw/branch/main/scripts/install.sh | \
  sudo TYTO_MODE=agent bash

Configure the agent:

# /etc/tyto/config.yaml
mode: agent

agent:
  id: web-server-01
  server_url: tyto-server.example.com:9849
  interval: 5s
  tls:
    ca_cert: /etc/tyto/certs/ca.crt
    agent_cert: /etc/tyto/certs/agent.crt
    agent_key: /etc/tyto/certs/agent.key

4. Approve Agents

New agents appear in the dashboard under Agents → Pending. Approve them to start receiving metrics.

Agent Log Collection

agent:
  logs:
    enabled: true
    buffer_size: 1000
    flush_interval: 5s
    journal:
      enabled: true
      units: [nginx.service, docker.service]
      priority: 4
    files:
      - path: /var/log/nginx/access.log
        format: nginx
    docker:
      enabled: true

PKI Management

tyto pki list --ca-dir /etc/tyto/pki/           # List certificates
tyto pki info --ca-dir /etc/tyto/pki/           # Show CA info
tyto pki revoke --serial ABC123 --ca-dir /etc/tyto/pki/  # Revoke cert

---

Authentication & Security

Local Authentication

# Create admin during setup
tyto setup --admin-user admin --admin-pass <password>

# Or via API
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "secret", "email": "admin@example.com"}'

LDAP/Active Directory

auth:
  ldap:
    enabled: true
    url: ldap://ad.example.com:389
    base_dn: dc=example,dc=com
    bind_dn: cn=readonly,dc=example,dc=com
    bind_password: ${LDAP_BIND_PASSWORD}
    user_filter: (sAMAccountName=%s)
    group_mappings:
      "CN=Tyto Admins,OU=Groups,DC=example,DC=com": admin
      "CN=Tyto Operators,OU=Groups,DC=example,DC=com": operator

Role-Based Access Control

Role	Permissions
Administrator	Full system access (*)
Operator	Manage agents, alerts, view/export metrics
Viewer	Read-only dashboard access

Available permissions

• dashboard:view - View dashboard
• agents:view, agents:manage - Agent management
• alerts:view, alerts:acknowledge, alerts:configure - Alert handling
• users:view, users:manage - User management
• roles:view, roles:manage - Role management
• metrics:export, metrics:query - Metrics access
• pki:manage - Certificate management

---

API Reference

Metrics & Monitoring

Method	Endpoint	Description
GET	/api/v1/stream	SSE stream of real-time metrics
GET	/api/v1/history	Historical metric data
GET	/api/v1/alerts	Current alerts
POST	/api/v1/alerts/config	Update alert thresholds
POST	/api/v1/alerts/:id/acknowledge	Acknowledge alert
GET	/api/v1/processes/:pid	Process details
POST	/api/v1/processes/:pid/signal	Send signal to process
GET	/api/v1/export/metrics?format=csv|json	Export metrics
GET	/health	Health check

Authentication

Method	Endpoint	Description
POST	/api/v1/auth/login	Login
POST	/api/v1/auth/logout	Logout
POST	/api/v1/auth/register	Register (if enabled)
GET	/api/v1/auth/me	Current user info
PUT	/api/v1/auth/me	Update profile
PUT	/api/v1/auth/me/password	Change password

User & Role Management

Method	Endpoint	Description
GET	/api/v1/users	List users
POST	/api/v1/users	Create user
GET	/api/v1/users/:id	Get user
PUT	/api/v1/users/:id	Update user
DELETE	/api/v1/users/:id	Disable user
GET	/api/v1/roles	List roles
POST	/api/v1/roles	Create role
PUT	/api/v1/roles/:id	Update role
DELETE	/api/v1/roles/:id	Delete role

Agent Management

Method	Endpoint	Description
GET	/api/v1/agents	List agents
GET	/api/v1/agents/:id	Get agent
POST	/api/v1/agents	Add agent
DELETE	/api/v1/agents/:id	Remove agent
POST	/api/v1/agents/:id/revoke	Revoke certificate
GET	/api/v1/agents/pending	Pending registrations
POST	/api/v1/agents/pending/:id/approve	Approve agent
POST	/api/v1/agents/pending/:id/reject	Reject agent

Logs

Method	Endpoint	Description
GET	/api/v1/logs	Query logs
GET	/api/v1/logs/stream	SSE log stream

SSE Stream Format

{
  "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, "gpus": [...] },
  "docker": { "available": true, "containers": [...] },
  "systemd": { "available": true, "services": [...] }
}

---

Deployment

Docker Compose

Development:

docker compose up -d

Production (with resource limits):

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Systemd Service

systemctl status tyto      # Check status
journalctl -u tyto -f      # View logs
systemctl restart tyto     # Restart

Building from Source

# Build Docker images
docker compose build

# Build binaries
cd backend && go build -o tyto ./cmd/server
cd backend && go build -o tyto-agent ./cmd/agent

---

Development

Prerequisites

• Go 1.23+
• Node.js 22+
• Docker & Docker Compose

Local Development

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

# Frontend
cd frontend
npm install
npm run dev

Running Tests

cd backend && go test ./...
cd frontend && npm test

Project Structure

tyto/
├── backend/
│   ├── cmd/
│   │   ├── server/          # HTTP/SSE server
│   │   ├── agent/           # Lightweight agent
│   │   └── tyto/            # CLI tool
│   ├── internal/
│   │   ├── api/             # HTTP handlers
│   │   ├── auth/            # Authentication
│   │   ├── collectors/      # Metric collectors
│   │   │   ├── gpu/         # Multi-vendor GPU
│   │   │   └── logs/        # Log collectors
│   │   ├── database/        # SQLite/PostgreSQL
│   │   ├── pki/             # Certificate management
│   │   └── server/          # gRPC hub
│   └── proto/               # gRPC definitions
├── frontend/
│   ├── src/
│   │   ├── lib/
│   │   │   ├── components/  # Svelte components
│   │   │   ├── stores/      # State management
│   │   │   └── api/         # API clients
│   │   └── routes/          # Pages
├── scripts/
│   └── install.sh
├── docker-compose.yml
└── docker-compose.prod.yml

---

Troubleshooting

No metrics displayed

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

GPU not detected

AMD GPU:

• Requires amdgpu driver
• Mount: -v /sys:/host/sys:ro

NVIDIA GPU:

• Requires nvidia-smi in PATH
• Docker: --gpus all or nvidia-container-toolkit

Intel GPU:

• Requires i915 or xe driver
• Mount: -v /sys:/host/sys:ro

Docker containers not showing

Mount the Docker socket:

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

Systemd services not showing

Mount the D-Bus socket:

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

Agent not connecting

1. Verify server is running with TYTO_MODE=server
2. Check agent certificate is valid: tyto pki list
3. Ensure port 9849 is accessible
4. Check agent logs: journalctl -u tyto -f

---

License

MIT License - see LICENSE for details.

---

Back to top