114 lines
6.4 KiB
Markdown
114 lines
6.4 KiB
Markdown
# AI Agent Infrastructure Strategy: Homelab Management
|
|
|
|
This document establishes the architecture, workflow rules, and skill definitions for an AI agent to interface with the self-hosted environment using the Model Context Protocol (MCP) and local system aliases.
|
|
|
|
---
|
|
|
|
## 1. Primary AI Workspace and Persistence Directive
|
|
|
|
The agent must treat the `/srv/configs/ai` directory as its absolute source of truth for its own configuration, execution memory, and custom skill scripts.
|
|
|
|
### Operational Rules
|
|
|
|
* **Storage Location:** All agent workflows, system prompts, automated rules, markdown runbooks, and custom skill definitions *must* be stored in `/srv/configs/ai/`.
|
|
* **State Management:** Before executing any systemic infrastructure review, the agent must read the current context files in this directory to ensure it is operating under the latest user definitions.
|
|
* **No Side Effects:** The agent is strictly prohibited from writing or modifying configuration files outside of this path unless explicitly authorized by the user during an interactive session.
|
|
|
|
---
|
|
|
|
## 2. Homelable MCP Server Integration
|
|
|
|
The agent leverages the Model Context Protocol to interface directly with the `homelable-mcp` container running locally. This allows the agent to bind physical network topologies to visual infrastructure diagrams.
|
|
|
|
### Connection Architecture
|
|
|
|
* **Location:** Co-located on the same local host node.
|
|
* **Transport Method:** Server-Sent Events (SSE) or local port binding.
|
|
* **API Endpoint:** `http://localhost:8001`
|
|
|
|
### Capabilities Matrix
|
|
|
|
| Permission | Action | Operational Boundaries |
|
|
| ---------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
|
|
| **Read** | List all nodes, edges, full canvas, pending devices, scan history. | Executed proactively during an audit cycle. |
|
|
| **Write** | Add/update/delete nodes and edges, trigger network scans, approve/hide discovered devices. | **DISABLED BY DEFAULT.** Requires explicit, per-action user confirmation. |
|
|
|
|
---
|
|
|
|
## 3. Host System Execution Environment & Aliases
|
|
|
|
The agent interacts with the host infrastructure by executing commands directly within the host shell session. It relies on system aliases defined in the central configuration file.
|
|
|
|
* **Alias Configuration File:** `/srv/configs/.bash_aliases`
|
|
|
|
### Required Core Aliases
|
|
|
|
The agent must parse and respect the following explicit wrappers found in the alias file:
|
|
|
|
* `docker-service`: Used to query container states, image updates, and running stacks.
|
|
* `nginx`: Used to inspect reverse proxy server blocks, active upstreams, and active domain routings.
|
|
|
|
---
|
|
|
|
## 4. Skill Definition: Infrastructure Reconciliation & Audit
|
|
|
|
### Skill Name
|
|
|
|
`review_homelab_infrastructure`
|
|
|
|
### Objective
|
|
|
|
Cross-reference the active compute and reverse-proxy states against the `homelable` canvas topology and the primary markdown infrastructure log.
|
|
|
|
### Source of Truth Inventory Documentation
|
|
|
|
* **Target File:** `/srv/docs/public/projects/homelab/homelab_Infra.md`
|
|
* **Policy:** The agent must maintain and preserve the existing structural formatting of this file when suggesting updates.
|
|
|
|
### Execution Workflow
|
|
|
|
```
|
|
[Trigger: Audit Command]
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ 1. Parse aliases via `/srv/configs/.bash_aliases` │
|
|
│ 2. Read active inventory from `homelab_Infra.md` │
|
|
│ 3. Fetch live container states via `docker-service` │
|
|
│ 4. Fetch proxy mappings via host `nginx` commands │
|
|
│ 5. Pull active topology via Homelable MCP (Port 8001) │
|
|
└─────────────────────────┬──────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Perform 3-Way Reconciliation │
|
|
│ (homelab_Infra.md vs. Live States vs. MCP Canvas) │
|
|
└─────────────────────────┬──────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────┐
|
|
│ Generate Diff Report & Proposed Changes (Markdown) │
|
|
└─────────────────────────┬──────────────────────────────┘
|
|
│
|
|
▼
|
|
{ User Explicitly Approves? }
|
|
/ \
|
|
(Approved) (Denied)
|
|
/ \
|
|
▼ ▼
|
|
┌─────────────────────────┐ ┌─────────────────────────┐
|
|
│ - Update MCP Canvas │ │ Abort & Log Audit │
|
|
│ - Append/Modify │ │ Failure in Workspace │
|
|
│ homelab_Infra.md │ │ (/srv/configs/ai/) │
|
|
└─────────────────────────┘ └─────────────────────────┘
|
|
|
|
```
|
|
|
|
### Safety and Guardrails
|
|
|
|
> [!IMPORTANT]
|
|
> **Strict Read-Only Default:** The agent is explicitly forbidden from making automatic writes or commits.
|
|
> * **No silent canvas updates:** Every node change, edge modification, or scan approval on the Homelable MCP requires manual confirmation.
|
|
> * **No silent documentation updates:** Under no circumstances should the agent modify `/srv/docs/public/projects/homelab/homelab_Infra.md` without presenting a clear diff block and receiving confirmation first.
|
|
>
|
|
> |