sysdock 2.0.0

Lean cross-platform monitoring agent: terminal + web dashboard, Prometheus metrics, and a security panel (firewall, open ports, failed auth).

SysDock 🚀

Built and independently maintained by Kavy Vachhani

Modern cross-platform monitoring agent — Linux, macOS, and Windows — with a live terminal dashboard, Docker metrics, and pip-installable CLI.

---

⚡ What is SysDock?

SysDock is a lightweight, zero-configuration monitoring tool for Linux, macOS, and Windows. It runs completely in the terminal and provides real-time insights into your system's performance, Docker containers, and live firewall rules.

Think of it as htop + docker stats + ufw status rolled into one beautiful dashboard, running natively on any platform!

pipx install sysdock
sysdock          # opens the live dashboard instantly

---

✨ Features

• 🖥 Live Terminal Dashboard — Monitor CPU per-core, RAM, disk, network throughput, processes, and security.
• 🐳 Laser-Accurate Docker Metrics — CPU %, true memory usage (correctly subtracting page caching), and network I/O per container exactly matching the docker stats formula.
• 📊 htop-Grade Accuracy — CPU sampled perfectly at precise intervals; RAM utilizes the authentic htop free/buffers/cached formula.
• 🛡️ Active Firewall & Security Panel — Live UFW (Uncomplicated Firewall) status, permitted port rules, SSH failures, and fail2ban tracking directly on the dashboard.
• 🌐 Built-in HTTP API — Instantly export metrics as a JSON snapshot or via a live SSE (Server-Sent Events) network stream without external agents.
• 🛠 Zero Configuration — Works cleanly on almost any Linux distribution with Python 3.6+. No heavy daemons needed.

---

📦 Installation

We highly recommend using pipx (or a standard pip environment) for clean installation:

# Recommended standard install
pipx install sysdock

# Install with native Docker SDK (richer container stats)
pipx install "sysdock[docker]"

# Upgrade to the latest version
pipx upgrade sysdock

Note: If pipx is not available on your system, standard pip install sysdock works beautifully as well.

---

💻 Native App Installers (macOS, Windows, Linux)

Download the latest pre-built native installer directly from GitHub Releases:

Platform	Installer	How to Install
🍎 macOS	SysDock_macOS.pkg	Double-click the .pkg — installs SysDock.app into /Applications
🐧 Linux	sysdock_linux.deb	sudo dpkg -i sysdock_linux.deb
🪟 Windows	SysDock_Windows.zip	Extract the zip, run sysdock.exe

🍎 macOS Step-by-Step

1. Download SysDock_macOS.pkg from Releases
2. Double-click it to run the macOS Installer
3. SysDock.app is installed into your /Applications folder
4. Open it from Launchpad or Spotlight — it launches its own window!

🪟 Windows Step-by-Step

1. Download SysDock_Windows.zip from Releases
2. Extract the zip file
3. Double-click sysdock.exe inside the extracted folder — no installation required!

🐧 Linux (Debian/Ubuntu)

wget https://github.com/Kavyvachhani/SysDock/releases/latest/download/sysdock_linux.deb
sudo dpkg -i sysdock_linux.deb
sysdock

Native installers are automatically built and published to GitHub Releases on every version tag.

---

🚀 Quick Reference

sysdock              # open live dashboard (default)
sysdock dash         # same as above
sysdock web          # serve web dashboard + JSON API + live stream on 127.0.0.1:8787
sysdock status       # one-shot snapshot (rich table)
sysdock status --json               # full snapshot as JSON
sysdock status --top 20             # show more processes
sysdock status --no-docker          # skip Docker collection
sysdock check        # report detected capabilities (--json for raw)
sysdock version      # print version
sysdock install      # install as a systemd background service (requires root)
sysdock uninstall    # remove background service (requires root)

---

📡 Web Dashboard & HTTP API

sysdock web serves a built-in dashboard, a JSON snapshot API, a live SSE stream, and a Prometheus endpoint — all from a single shared snapshot (N clients never trigger N collections). It uses the Python standard library only; no web framework is pulled in.

sysdock web                       # 127.0.0.1:8787 — loopback only, no auth needed
sysdock web --host 0.0.0.0        # expose it — a bearer token is generated & printed once
sysdock web --port 9000 --no-metrics

Endpoint	Description
GET /	Built-in web dashboard (HTML/CSS/JS)
GET /api/snapshot	Full JSON snapshot — host, cpu, memory, disk, network, processes, docker, security, gpu
GET /api/stream	Server-Sent Events — pushes a live snapshot every ~2 seconds
GET /metrics	Prometheus text exposition (disable with --no-metrics)
GET /health	Basic {"status": "ok"} check (always unauthenticated)

Security: binds 127.0.0.1 by default. Any non-loopback bind requires a bearer token (auto-generated, printed once, persisted; rotate with --regen-token). Responses carry strict security headers and a locked-down CSP, tokens never appear in URLs or logs, and requests are rate-limited per client IP. Terminate TLS with a reverse proxy and restrict the port at your firewall when exposing it. --no-auth on a non-loopback bind is for trusted networks only.

---

🎯 Metric Accuracy Details

SysDock takes immense pride in providing data that you can actually trust:

Metric	Method
CPU %	1-second delta sampling per core (identical to htop)
RAM used	total − free − buffers − cached (authentic htop formula)
Docker CPU	(cpu_delta / sys_delta) × nCPUs × 100 (matches docker stats)
Docker Memory	Subtracts page caching (inactive_file/cache) from raw memory usage

---

🐧 Compatibility

Distro	Status
Ubuntu 20.04 / 22.04 / 24.04	✅ Fully Supported
Debian 10 / 11 / 12	✅ Fully Supported
Amazon Linux 2 / 2023	✅ Fully Supported
CentOS / RHEL (7 / 8 / 9)	✅ Fully Supported
Alpine / Arch Linux	✅ Fully Supported

Cross-platform (Linux, macOS, Windows); requires Python 3.9 – 3.13.

---

💼 License & Links

• PyPI Package: pypi.org/project/sysdock
• Source Code: github.com/Kavyvachhani/SysDock
• Issue Tracker: github.com/Kavyvachhani/SysDock/issues

MIT License © 2026 built by Kavy Vachhani