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.

6.4 KiB Raw Blame History