https://github.com/luvaary/sentinel
open source system monitoring program, written in python
https://github.com/luvaary/sentinel
cross-platform developer-tools fastapi offline-first open-source performance-monitoring privacy-first psutil python self-hosted sqlite system-monitor web-dashboard
Last synced: 6 months ago
JSON representation
open source system monitoring program, written in python
- Host: GitHub
- URL: https://github.com/luvaary/sentinel
- Owner: luvaary
- Created: 2025-12-21T21:52:56.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-21T21:59:09.000Z (6 months ago)
- Last Synced: 2025-12-23T09:35:47.260Z (6 months ago)
- Topics: cross-platform, developer-tools, fastapi, offline-first, open-source, performance-monitoring, privacy-first, psutil, python, self-hosted, sqlite, system-monitor, web-dashboard
- Language: JavaScript
- Homepage:
- Size: 12.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🛡️ 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:
```bash
pip install -r requirements.txt
```
## Running Sentinel
Start the server:
```bash
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`:
```python
uvicorn.run(app, host="127.0.0.1", port=8001)
```
### Permission Errors
Some system metrics may require elevated permissions. Run with:
```bash
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.