🛡️ Sentinel

A Python-powered, self-hosted system monitoring web application.

Overview

Sentinel provides real-time and historical insights into your computer's system health through a clean web dashboard. Everything runs locally on your machine with no cloud services, accounts, or telemetry.

Features

• Real-time monitoring: CPU, RAM, disk usage, and system uptime
• Process overview: View top processes by CPU and memory usage
• Historical tracking: Visualize system metrics over time with interactive charts
• Health alerts: Automatic warnings for high resource usage
• Privacy-first: All data stored locally, no internet required
• Cross-platform: Works on Linux, macOS, and Windows

Tech Stack

• Backend: Python 3, FastAPI, psutil, SQLite
• Frontend: HTML, CSS, JavaScript, Chart.js
• Server: Uvicorn (ASGI)

Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Setup

1. Clone or download this repository
2. Navigate to the project directory
3. Install dependencies:

pip install -r requirements.txt

Running Sentinel

Start the server:

python main.py

Open your browser and navigate to:

http://localhost:8000

The dashboard will load automatically.

Usage

Dashboard Features

• Current Stats Cards: View real-time CPU, RAM, disk, and process count
• Alerts: Get notified when resources exceed safe thresholds
• Historical Charts: Toggle between 1, 6, or 24-hour views
• Top Processes: Monitor which processes are using the most resources

Data Storage

Sentinel stores historical metrics in a local SQLite database (sentinel.db). This file is created automatically on first run.

Refresh Rates

• Current stats: Every 2 seconds
• Processes: Every 5 seconds
• Historical charts: Every 10 seconds

Project Structure

sentinel/
├── main.py              # FastAPI backend server
├── requirements.txt     # Python dependencies
├── sentinel.db         # SQLite database (auto-created)
├── static/
│   ├── index.html      # Dashboard interface
│   ├── style.css       # Styling
│   └── app.js          # Frontend logic
└── README.md           # This file

Alert Thresholds

Sentinel triggers alerts when:

• CPU usage exceeds 80%
• RAM usage exceeds 85%
• Disk usage exceeds 90%

Privacy & Security

• No internet required: Runs entirely offline
• No cloud services: All data stays on your machine
• No user accounts: No authentication needed
• Local only: Accessible only via localhost by default

Stopping Sentinel

Press Ctrl+C in the terminal where the server is running.

Troubleshooting

Port Already in Use

If port 8000 is already in use, modify the port in main.py:

uvicorn.run(app, host="127.0.0.1", port=8001)

Permission Errors

Some system metrics may require elevated permissions. Run with:

sudo python main.py  # Linux/macOS

Database Locked

If you see database lock errors, ensure only one instance of Sentinel is running.

Future Extensions

Possible enhancements:

• Network usage monitoring
• Multi-machine monitoring (LAN)
• Export reports (CSV/JSON)
• Custom alert thresholds
• Plugin system for custom metrics

License

Open source. Use freely.

Why Python?

This project demonstrates Python's power for:

• Backend web development
• Systems programming
• API design
• Data visualization
• Real-world production applications

Sentinel is proof that Python is not "just a learning language" — it powers real, useful tools.