sysdock 3.0.1

Lean cross-platform monitoring agent for the terminal and native app: live dashboard, baseline-aware anomaly insights, persistent history, 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, baseline-aware anomaly insights, and a persistent history it remembers. Terminal & native-app only: no server, no open port.

---

⚡ 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 measured as a true delta between refreshes (never a misleading instantaneous 0%); RAM utilizes the authentic htop free/buffers/cached formula.
• 🛡️ Cross-Platform Security Panel — One normalized firewall / open-ports / failed-auth view on every OS: Linux (UFW → nftables → iptables, fail2ban, journald/auth.log), macOS (Application Firewall via socketfilterfw, unified-log auth failures), and Windows (Get-NetFirewallProfile, Security-log event 4625). A capability that isn't present degrades cleanly to "unavailable — reason", never a crash.
• 🔎 Baseline-Aware Anomaly Insights — Unlike fixed-threshold monitors, SysDock learns what's normal for this machine and flags what's unusual — spikes, sustained pressure, and slow leaks — and names the culprit process (e.g. “CPU 94% now vs ~18% typical · likely ffmpeg (pid 8821)”). sysdock insights, plus a live band in the dashboard.
• 🧠 Its Own Memory — SysDock persists a lightweight local history (standard-library SQLite, no daemon) so it can show real trends, baselines, and peaks over the last hour/day/week — not just the instantaneous value. sysdock history renders min/avg/max + sparklines per metric.
• 🛠 Zero Configuration — Runs out of the box on Linux, macOS, and Windows with Python 3.9+. No heavy daemons, no config files.

---

📦 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 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 insights     # flag anomalies vs. this machine's learned baseline
sysdock insights --json             # findings as JSON
sysdock record       # headless recorder — builds history (no server/browser)
sysdock record --interval 10        # sample every 10s
sysdock rewind --peak cpu           # time-travel to the worst CPU moment on record
sysdock rewind --ago 10m            # what was running 10 minutes ago
sysdock rewind 14:30                # …at 14:30 today
sysdock history      # show recorded trends (its own memory): min/avg/max + sparklines
sysdock history --window 7d         # summarise the last 7 days
sysdock history --json              # raw history summary as JSON
sysdock history --clear             # wipe the local history store
sysdock check        # report detected capabilities (--json for raw)
sysdock version      # print version
sysdock install      # install the headless recorder as a background service (root)
sysdock uninstall    # remove background service (requires root)

---

🔎 Anomaly Insights (what stateless monitors can't do)

htop / btop / glances color a value red at a fixed threshold — they have no memory, so they can't tell you whether what you're seeing right now is unusual for this machine. SysDock keeps a persistent baseline and turns it into plain-language, actionable findings — including which process is responsible.

sysdock insights          # evaluate the current reading vs. the learned baseline
sysdock insights --json   # machine-readable findings

It detects:

• Spikes — a reading that is both statistically unusual (z-score over the metric's own spread) and materially above its baseline, with the culprit process attributed (e.g. “CPU 94% now vs ~18% typical · likely ffmpeg (pid 8821, 190% CPU)”).
• Sustained pressure — chronically high averages, not just transient blips.
• Slow upward creep on memory/swap that looks like a leak — invisible to a threshold monitor until it's already on fire.
• Cross-subsystem correlation — when two subsystems are anomalous together, it names the root cause: RAM + swap → "system is paging", CPU + disk → "likely I/O-bound".

The same findings appear as a live Insights band in the terminal dashboard (alongside per-metric sparklines of the recent trend). The engine is conservative: it stays quiet until it has a trustworthy baseline and only speaks when a move is genuinely abnormal — so no alert fatigue.

⏪ Time-travel (flight recorder)

SysDock records the top processes alongside every metric sample, so you can rewind to a past spike and see what was running then — something no stateless monitor (htop/btop/glances) can do, because they keep no history.

sysdock rewind --peak cpu      # jump straight to the worst CPU moment on record
sysdock rewind --ago 10m       # reconstruct the system 10 minutes ago
sysdock rewind 03:14           # …at 03:14 today (when that alert fired)

It reconstructs the metrics and the process table for that instant, bounded so it never borrows a process list from a different time.

Terminal & native app only — no browser. SysDock runs in your terminal or as a native app window; there is no web server, no open port, and nothing to expose. History is built locally by sysdock record (or each sysdock status).

---

🧠 Its Own Memory (Persistent History)

Most terminal monitors are amnesiac — they only ever show now. SysDock keeps a small local SQLite database (standard library only, no daemon) and folds each snapshot into it, so it can tell you what normal looks like on this machine.

sysdock history                 # trends over the last 24h (min/avg/max + sparklines)
sysdock history --window 7d     # the last week
sysdock history --json          # machine-readable summary

History accrues automatically whenever sysdock record runs (continuously) or each time you run sysdock status. The database is bounded by automatic retention (7 days) and a hard row cap, so it stays lightweight forever. It lives at:

Platform	Location
🐧 Linux	$XDG_DATA_HOME/sysdock/history.db (default ~/.local/share/sysdock/)
🍎 macOS	~/Library/Application Support/sysdock/history.db
🪟 Windows	%LOCALAPPDATA%\sysdock\history.db

Override the location with SYSDOCK_DATA_DIR. Wipe it any time with sysdock history --clear.

---

🎯 Metric Accuracy Details

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

Metric	Method
CPU %	delta between refreshes, per core (same model as 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