Homelab Nexus

Why Build a Command Center?

A growing homelab accumulates services across multiple hosts - databases, orchestration tools, storage, virtualization. Tracking what’s running where becomes a chore:

• Services are scattered across Proxmox VMs, TrueNAS, and bare metal
• Credentials live in .env files, password managers, and Infisical
• No single view of what’s healthy vs. what’s down
• Running Claude Code requires terminal access to each machine

Homelab Nexus centralizes discovery, monitoring, and management into one interface with an integrated Claude Code terminal.

Architecture

Three services work together:

┌─────────────────────────────────────────────────────────────┐
│                      SvelteKit Web UI                        │
│           Glass neomorphic dark theme + runes                │
└─────────────────────────────────────────────────────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
        ┌─────────┐   ┌─────────┐   ┌─────────┐
        │ FastAPI │   │   Go    │   │  Redis  │
        │   API   │   │ Bridge  │   │  Cache  │
        └─────────┘   └─────────┘   └─────────┘
              │             │
              ▼             ▼
        ┌─────────┐   ┌─────────────────┐
        │PostgreSQL│   │ Network Scanner │
        │ + pgvec │   │ + Claude CLI    │
        └─────────┘   └─────────────────┘

Key Features

Network Discovery

The Go bridge scans configured subnets for known ports and identifies services:

• Port scanning with configurable ranges
• Banner grabbing for service identification
• Automatic database population
• Health check scheduling

In-Browser Claude Code

The chat panel connects via WebSocket to the bridge, which wraps the local Claude CLI:

• Run skills (/discover, /health-check)
• Execute agent tasks with full context
• Interactive conversations
• No terminal hopping required

Credential Management

Credentials flow through Infisical:

1. Discovered in local .env files or Infisical
2. Associated with services
3. Tested for validity
4. Synced bidirectionally

MCP Server

The API exposes an MCP-compatible interface at /mcp:

Tools:

• list_services - List all discovered services
• get_service - Get service details
• refresh_service - Check service status
• start_discovery - Begin network scan
• sync_secrets - Sync with Infisical

Resources:

• nexus://services - All services
• nexus://discovery - Discovery jobs
• nexus://credentials - Credential metadata

Summary