# Introduction

![socktop logo](https://raw.githubusercontent.com/jasonwitty/socktop/master/docs/socktop_demo.apng)

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