Home

HomePilot

AI-first, artifact-backed, MCP-native homelab management platform.

HomePilot lets you manage your homelab through structured artifacts — proposed by AI, reviewed by you, applied via SSH or Ansible. Every change is tracked, reversible, and auditable.

Why HomePilot?

Artifact-driven: The AI never mutates infrastructure directly. It drafts a fully-specified plan (an artifact); you review and approve it before execution.
MCP-native: Exposes an MCP server (stdio or HTTP) so AI clients like Claude Code can query your inventory, search the knowledge base, and propose changes.
Zero-secrets deployment: No HomePilot secrets in .env files. Everything is stored in an age-encrypted vault.
Full audit trail: Every artifact lifecycle transition is recorded in an append-only audit log.

Quick Start

Docker (recommended)

git clone https://github.com/mtclab/homepilot-core-public.git
cd homepilot-core-public
cp .env.example .env
# Edit .env — at minimum set HP_PROXMOX_HOST
docker compose up -d
docker compose exec backend hp init
docker compose exec backend hp token create

Web UI: http://localhost:8000/ui

Local Development

pip install homepilot
hp init
hp mcp-serve   # stdio transport (default)

MCP Client Configuration

stdio (local):

{
  "mcpServers": {
    "homepilot": { "command": "hp", "args": ["mcp-serve"] }
  }
}

HTTP (remote):

HP_MCP_TOKEN=<secret> hp mcp-serve --transport http --host 0.0.0.0 --port 8000

{
  "mcpServers": {
    "homepilot": {
      "url": "http://homepilot.example.com:8000/mcp",
      "headers": { "Authorization": "Bearer <secret>" }
    }
  }
}

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│  AI CLIENT  (Claude Code, opencode, any MCP client)             │
│                                                                  │
│   ┌──────────────┐                                               │
│   │ MCP Client    │── HTTP or stdio ──▶  /mcp  endpoint         │
│   └──────────────┘                                               │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│  HOMELAB SERVER                                                 │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  hp mcp-serve                                            │   │
│  │  MCP tools: query_inventory, propose_artifact, etc.     │   │
│  └─────────┬────────────────────────┬──────────────────────┘   │
│            │                        │                           │
│  ┌─────────▼──────────┐  ┌─────────▼──────────────────────┐   │
│  │  Core Services      │  │  Data Layer                    │   │
│  │  ArtifactLifecycle  │  │  SQLite (hosts, artifacts,     │   │
│  │  ArtifactExecutor   │  │    KB, audit log, vec index)  │   │
│  │  KBService          │  │  Artifact Store (markdown)     │   │
│  │  InventoryService   │  │  Vault (age-encrypted)        │   │
│  │  VaultManager       │  │                                │   │
│  │  EventBus/Webhooks  │  │                                │   │
│  └─────────┬──────────┘  └────────────────────────────────┘   │
│            │                                                     │
│   ┌────────┼────────────┐                                       │
│   ▼        ▼            ▼                                       │
│  Proxmox  SSH Jump   Adopted                                    │
│  REST API Server    Services                                    │
└─────────────────────────────────────────────────────────────────┘

CLI

hp init                       # first-run setup
hp mcp-serve                  # start MCP server (stdio or HTTP)
hp status                     # daemon info, vault state, counts
hp artifacts list             # list artifacts
hp artifacts show <id>        # show artifact detail
hp artifacts approve <id>    # approve a proposed artifact
hp artifacts apply <id>      # apply an approved artifact
hp artifacts revoke <id>     # revoke an applied artifact
hp inventory refresh          # sync inventory from Proxmox
hp vault set <name>           # store a secret
hp vault get <name>           # retrieve a secret
hp token create               # create an API token