-
-
stacksentinel
-
diagnosis
-
scanning and auditor
-
output
-
output selection and user approval
-
watchdog
Inspiration
Between constantly tweaking and customizing our own Ubuntu environments and diving deep into complex architectures for our coursework, We have experienced the frustration of broken dependencies and missing configuration files . For system administrators, this pain is magnified. Traditional monitoring tools only alerts after a critical service like Nginx or PostgreSQL has already crashed.
We wanted to move beyond reactive dashboards. Inspired by the rapid advancements in LLM reasoning, we thought: What if a server could diagnose its own raw logs and heal itself before a human even wakes up? That thought led to the creation of StackSentinel, an autonomous, edge-deployed digital sysadmin powered by OpenAI.
What it does
StackSentinel is a self-healing watchdog for your infrastructure. It runs quietly on your machine or server, tailing system logs in real time. The moment it spots a CRITICAL or ERROR signal, it hands that raw log context to an OpenAI model for diagnosis — no dashboards to babysit, no manual log-diving at 3 AM. Once the model proposes a fix, StackSentinel doesn't just blindly execute it. Every generated command passes through a local execution auditor that checks it against a strict allowlist and blocklist before anything touches the kernel. If the fix is safe, it's applied automatically and logged. If it's risky, it's blocked outright. A lightweight Flask-based Command and Control (C2) dashboard streams live telemetry from the root-level watchdog to a user-level UI, so you can watch diagnosis and remediation happen in real time — locally, with no public exposure by default.
How we built it
StackSentinel operates on a decoupled architecture designed for both privilege and absolute safety.
The Brain: The core watchdog is written in Python. It constantly tails system logs (/var/log or our dummy targets) and intercepts CRITICAL or ERROR flags.
The LLM Integration: Upon detecting an anomaly, the agent passes the raw log context to OpenAI's Responses API, using gpt-5.6-luna as a fast, low-cost default model. To handle potential API rate limits gracefully, the system is designed with an exponential backoff algorithm where the wait time \($T$\) for the \($n$-th\) retry is calculated as \(Tn=min(Tmax,Tbase⋅2n).\)
The Safety Net: Giving an AI root access is Risky. So, we built a local Python execution auditor that acts as a strict firewall. Before any LLM-generated bash command touches the kernel, it gets parsed and checked against a blocklist of destructive actions (e.g., rm -rf, sudo, and command chaining). Commands run through a small allowlist instead of raw shell=True execution.
The C2 Dashboard: We built a Flask-based Command and Control UI. Using Inter-Process Communication (IPC) via atomic JSON writes, the root-level watchdog securely streams telemetry to the user-level dashboard. The dashboard is local-only by default, keeping the attack surface small.
Challenges we ran into
Building a system that operating at the root level of a Linux machine brought some massive pitstops: Migrating the AI backbone: Reworking the core AI integration to the OpenAI's Responses API — from prompt structure to response parsing to shared config handling — required rebuilding the "brain" module from while keeping the rest of the watchdog stable.
Virtual Environment Isolation vs. Global Execution: Wrapping the project in a safe Python venv meant standard terminal shells like zsh couldn't find the Stack sentinel command. We've written the install.sh script which correctly navigats PATH variables and global pip install so the CLI works globally without breaking the system.
POSIX Permissions and Notifications: Running the watchdog via sudo -E causing clashes with desktop notification systems, crashing the script when trying to notify the user. We have refactored the notification logic (notifier.py) to fail gracefully instead of crashing the watchdog.
File Locks and Persistence Paths: Early on, app data leaked into the repo root and caused permission clashes between the root watchdog and the standard user account. we introduced a dedicated app_paths.py module so all of the state now lives cleanly under ~/.local/share/niramaya/.
Snapshot Safety: The original snapshot-restore logic extracted archives directly, which is unsafe. we rebuilt it to restore only targeted, expected paths instead of unpacking blindly into the filesystem root.
Accomplishments that we're proud of
Built a working end-to-end pipeline — from raw log tailing, to AI diagnosis, to safe automated remediation
Designed strict safety layer: no shell=True, no sudo chaining, no destructive commands, with every action logged and reversible by the snapshot feature.
Migrated the entire AI backbone to OpenAI without breaking the system.
Got a clean, global CLI install working (sudo ./install.sh) with no venv dependency for the users.
Shipped a live local dashboard that shows the watchdog's reasoning and actions in real time, not just a static log dump.
What we learned
This project was a helpful in learning low-level Linux administration and AI integration. we deepened our understanding of POSIX file permissions, atomic IPC mechanisms, and how to safely manage environment variables and take care of boundaries between the root-level watchdog and user-level dashboard. More importantly, I learned how to "tame" an LLM. By wrapping OpenAI's models in strict programmatic guardrails — a command allowlist, a destructive-action blocklist, and no shell=True
What's next for Stack Sentinel
In the future we want to expand Stack Sentinel into more powerful and adding ease of access while target for other operating systems too, want to have seperate version for learners and developers where right now i have added the learn version with this only but i want to build it slightly different versions like --> A complex but faster and reliable version for the developers who don't care about the ui part but want faster working and accuracy --> A good and ease dashboard like simpler one for the learners to get ease to the terminal.
Log in or sign up for Devpost to join the conversation.