socktop-webterm/docs/src/introduction.md

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

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
• Issue Tracker: Report bugs and request features on GitHub
• crates.io:
  • socktop - TUI client
  • socktop-agent - Background agent
  • socktop-connector - Library for integrations
• APT Repository: https://jasonwitty.github.io/socktop/

Next Steps

See Quick Start for installation.