Metadata-Version: 2.4
Name: sysdock
Version: 3.0.0
Summary: 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).
Author-email: Kavy Vachhani <kavyvachhani@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Kavyvachhani/SysDock
Project-URL: Issues, https://github.com/Kavyvachhani/SysDock/issues
Keywords: monitoring,anomaly-detection,observability,security,firewall,docker,sysadmin,tui,sysdock
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Environment :: Console
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: click>=8.0.0
Provides-Extra: docker
Requires-Dist: docker>=6.0.0; extra == "docker"
Provides-Extra: gpu
Requires-Dist: nvidia-ml-py>=12.0.0; extra == "gpu"
Provides-Extra: dev
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy<2.0,>=1.11.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Dynamic: license-file

<h1 align="center">SysDock 🚀</h1>
<p align="center"><b>Built and independently maintained by Kavy Vachhani</b></p>
<p align="center">
  <b>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.</b>
</p>

<p align="center">
  <a href="https://pypi.org/project/sysdock/"><img src="https://img.shields.io/pypi/v/sysdock.svg?color=blue" alt="PyPI version"></a>
  <a href="https://pypi.org/project/sysdock/"><img src="https://img.shields.io/pypi/pyversions/sysdock.svg" alt="Python versions"></a>
  <a href="https://github.com/Kavyvachhani/SysDock/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/sysdock.svg?color=green" alt="License"></a>
</p>

---

## ⚡ 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!

```bash
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:

```bash
# 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](https://github.com/Kavyvachhani/SysDock/releases/latest):

| 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](https://github.com/Kavyvachhani/SysDock/releases/latest)
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](https://github.com/Kavyvachhani/SysDock/releases/latest)
2. Extract the zip file
3. Double-click `sysdock.exe` inside the extracted folder — no installation required!

### 🐧 Linux (Debian/Ubuntu)
```bash
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](https://github.com/Kavyvachhani/SysDock/releases) on every version tag.

---

## 🚀 Quick Reference

```bash
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.

```bash
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.

```bash
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.

```bash
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](https://pypi.org/project/sysdock/)
- **Source Code:** [github.com/Kavyvachhani/SysDock](https://github.com/Kavyvachhani/SysDock)
- **Issue Tracker:** [github.com/Kavyvachhani/SysDock/issues](https://github.com/Kavyvachhani/SysDock/issues)

MIT License © 2026 built by **Kavy Vachhani**
