83 lines
3.5 KiB
Markdown
83 lines
3.5 KiB
Markdown
|
# Introduction
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
**socktop** is a TUI-first remote system monitor built with Rust. Two components:
|
||
|
|
|
||
|
|
- **socktop (TUI Client)** - A terminal-based user interface for viewing system metrics
|
||
|
|
- **socktop-agent** - A lightweight background service that collects and serves system metrics over WebSocket
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
- TUI built with ratatui, Catppuccin Frappe theme
|
||
|
|
- CPU: overall sparkline + per-core bars, accurate per-process CPU% (normalized 0-100%)
|
||
|
|
- Memory/Swap gauges
|
||
|
|
- Disks: per-device usage
|
||
|
|
- Network: per-interface throughput with sparklines
|
||
|
|
- Temperatures: CPU (optional)
|
||
|
|
- Top processes (top 50): sortable by CPU% or memory, scrollable
|
||
|
|
- Optional GPU metrics
|
||
|
|
- Remote monitoring via WebSocket (JSON over WS)
|
||
|
|
- Optional WSS (TLS): agent auto-generates self-signed cert on first run, client pins cert via --tls-ca/-t
|
||
|
|
- Optional auth token
|
||
|
|
- Connection profiles for quick access to saved hosts
|
||
|
|
- Built-in demo mode (--demo)
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
socktop uses a client-server architecture:
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────┐ WebSocket ┌──────────────────┐
|
||
|
|
│ │ ◄────────────────────────► │ │
|
||
|
|
│ socktop (TUI) │ (with TLS optional) │ socktop-agent │
|
||
|
|
│ Client │ │ (Background) │
|
||
|
|
│ │ │ │
|
||
|
|
└─────────────────┘ └──────────────────┘
|
||
|
|
│ │
|
||
|
|
│ │
|
||
|
|
▼ ▼
|
||
|
|
User Terminal System Metrics
|
||
|
|
Local or Remote (sysinfo crate)
|
||
|
|
```
|
||
|
|
|
||
|
|
The agent runs on each system you want to monitor, collecting metrics using the `sysinfo` crate. The client connects to one or more agents to display real-time system information.
|
||
|
|
|
||
|
|
## Quick Demo
|
||
|
|
|
||
|
|
```bash
|
||
|
|
socktop --demo
|
||
|
|
```
|
||
|
|
|
||
|
|
Spins up a temporary local agent on port 3231 and connects to it. Stops automatically when you quit.
|
||
|
|
|
||
|
|
## Use Cases
|
||
|
|
|
||
|
|
- Remote server monitoring
|
||
|
|
- Homelab / Raspberry Pi cluster monitoring
|
||
|
|
- Development / testing resource usage
|
||
|
|
- Custom dashboards via `socktop_connector` library
|
||
|
|
|
||
|
|
## Project Status
|
||
|
|
|
||
|
|
socktop is actively maintained and used in production environments. The project follows semantic versioning and maintains backward compatibility within major versions.
|
||
|
|
|
||
|
|
- **Current Version**: 1.50.x
|
||
|
|
- **Minimum Rust Version**: 1.70+
|
||
|
|
- **Supported Platforms**: Linux (amd64, arm64, armhf, riscv64)
|
||
|
|
- **License**: MIT
|
||
|
|
|
||
|
|
## Community and Support
|
||
|
|
|
||
|
|
- **GitHub Repository**: [https://github.com/jasonwitty/socktop](https://github.com/jasonwitty/socktop)
|
||
|
|
- **Issue Tracker**: Report bugs and request features on GitHub
|
||
|
|
- **crates.io**:
|
||
|
|
- [socktop](https://crates.io/crates/socktop) - TUI client
|
||
|
|
- [socktop-agent](https://crates.io/crates/socktop-agent) - Background agent
|
||
|
|
- [socktop-connector](https://crates.io/crates/socktop-connector) - Library for integrations
|
||
|
|
- **APT Repository**: [https://jasonwitty.github.io/socktop/](https://jasonwitty.github.io/socktop/)
|
||
|
|
|
||
|
|
## Next Steps
|
||
|
|
|
||
|
|
See [Quick Start](./installation/quick-start.md) for installation.
|