nearxos/Agentic-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add project documentation

Browse Source
This commit is contained in:
nearxos
2026-06-15 07:50:48 +03:00
parent 9fc35e86fe
commit 761dd0945c
5 changed files with 584 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/project-overview.md Normal file
View File

@@ -0,0 +1,69 @@
# Project Overview
## Purpose
Agentic OS is a Docker-based operations and troubleshooting platform for vessels and homelab infrastructure. It lets an operator describe an issue in plain language, select a vessel, and have an agent decide which onboard devices to inspect, run diagnostics through MCP tools, reason over the results, and produce a clean report.
The project is built around GeneseasX-style deployments, but the architecture is intentionally modular: Proxmox, pfSense, Asterisk, Debian/Docker hosts, FortiGate, FortiSwitch, and other device families are represented as inventory slots and routed to matching MCP integrations.
## Core Capabilities
- **Vessel inventory**: stores vessels/locations and onboard device records, including encrypted credentials.
- **Guided task creation**: previews which devices and checks will run before starting a task.
- **Agentic troubleshooting**: uses a LangGraph workflow to gather context, triage, diagnose, reason, and report.
- **MCP diagnostics**: launches or connects to device-specific MCP servers for read-only checks and approved write paths.
- **Tiered LLM routing**: starts with local Ollama and escalates to Gemini, DeepSeek, or OpenRouter tiers when needed.
- **Approvals**: gates config-changing actions and MCP self-development behind support/admin approval.
- **Live task status**: streams progress, current phase, device/tool activity, approvals, and final artifacts.
- **Concise reporting**: stores structured reports with findings, scope checked, evidence references, cost, and saved artifacts.
- **Persistent knowledge**: searches and writes to project-memory and an Obsidian vault so future tasks can reuse prior findings.
- **Operations dashboard**: highlights active tasks, attention items, recent findings, budgets, and MCP readiness.
## Primary Users
| User | Role in the system |
|---|---|
| `admin` | Full system administration, users, models, inventory, approvals, and task operations. |
| `support` | Creates/runs tasks, manages vessel inventory, approves safe actions. |
| `readonly` | Observes dashboards, inventory, tasks, timelines, and reports. |
## What Agentic OS Is Not
- It is not a replacement for the underlying firewalls, PBX, or hypervisor management UI.
- It does not automatically apply unsafe config changes without explicit approval.
- It should not store secrets in documentation, reports, memory entries, or committed files.
- It does not make unreachable infrastructure reachable; MCPs still require network access and valid credentials.
## Main Functional Areas
### Dashboard
The dashboard is the operator's first view. It summarizes:
- active tasks and their status;
- tasks needing approval or attention;
- failed tasks and artifact push failures;
- recent findings and saved reports;
- cloud API balances;
- MCP server readiness.
### Inventory
Inventory models vessels and onboard devices. Each device has a catalog key, device type, address, port, MCP server, username, and encrypted secret. Device defaults can be populated from environment variables so operators do not need to re-enter common credentials.
### Tasks
Tasks are the main unit of work. A task contains a title, issue text, target vessel, run history, live events, approvals, and final report. The task engine chooses devices from the issue text using troubleshooting rules and then runs device-specific diagnostics.
### Rules and Skills
Troubleshooting rules decide the device scope and standard hints. Skills add deeper procedure text for matching scenarios such as VoIP, DNS/captive portal, or pfSense change safety.
### MCP Management
The worker starts MCP servers as subprocess sidecars. MCP repos can be local folders or cloned from Gitea. The MCP page lets operators inspect loaded tools and perform maintenance actions such as reload, upgrade, and controlled MCP development.
### Reports and Knowledge
Reports are stored in Postgres, written to project-memory, and exported to Obsidian. The default UI shows concise findings; raw evidence remains available behind expandable sections.