HomelabCode

Chat-based agent that discovers, monitors, and manages homelab infrastructure.

HomelabCode is part of the XCode family (GodotCode, BlenderCode, HomelabCode) — same agent core, same tool architecture, different "world." HomelabCode's world is infrastructure topology.

What It Does

• Discovers your homelab: scans networks, detects running services, maps topology
• Monitors continuously: watches metrics, logs, and events via daemon mode
• Manages infrastructure: runs commands, manages containers, configures services through a chat interface
• Remembers: persistent memory across sessions, topology state saved to disk

Quick Start

Install

pip install homelabcode

With all adapter dependencies:

pip install homelabcode[adapters]

Configure

Create ~/.homelabcode/config.yaml:

provider: anthropic
api_key: sk-ant-...
model: claude-sonnet-4-20250514
permissions: default

# Optional: SSH defaults for discovery
ssh:
  username: root
  key_filename: ~/.ssh/id_ed25519

Or set environment variables:

export ANTHROPIC_API_KEY=sk-ant-...

Run

# Interactive REPL
homelabcode

# Single-shot query
homelabcode --print "list all running containers on pve1"

# Web UI (coming soon)
homelabcode --web

# Daemon mode (coming soon)
homelabcode --daemon

How It Works

Topology Discovery

HomelabCode builds a topology map of your infrastructure — every node, network, service, and storage volume it can find. This map persists at ~/.homelabcode/topology.json and is injected into every conversation as context.

Topology: 5 nodes, 4 reachable
Services: 23
Adapters: docker, proxmox, ssh, prometheus, traefik
Networks: 2

Adapter System

Each infrastructure service gets an adapter — a normalized interface that handles detection, connection, and health checks. Adapters are auto-detected during discovery. Available adapters:

Adapter	Service	Detects via
SSH	Remote shell	TCP port 22
Docker	Container management	Docker socket or TCP 2375/2376
Podman	Container management	Podman socket
Proxmox	VM management	HTTPS port 8006
TrueNAS	Storage management	HTTPS port 443
Kubernetes	Cluster management	~/.kube/config
K3s	Lightweight k8s	k3s kubeconfig
systemd	Service management	SSH + pidof systemd
Prometheus	Metrics	HTTP port 9090
Grafana	Dashboards	HTTP port 3000
Traefik	Reverse proxy	HTTP API port 8080
Dynu	DDNS	API key in config
Home Assistant	Smart home	HTTP port 8123
Nginx	Web server	SSH + nginx -t
Caddy	Web server	HTTP port 2019

Adapters are optional — missing dependencies are handled gracefully.

Architecture

homelab/
├── ai/              # LLM streaming (Anthropic, OpenAI), cost tracking
├── agent/           # Agent loop, tool dispatch, events
├── session/         # Context building, settings, session management
├── memory/          # Persistent markdown memory
├── permissions/     # Three modes: default, plan, bypass
├── extensions/      # Hot-reloadable extension system
├── undo/            # Operation log with rollback hints
├── topology/        # TopologyMap, discovery, watch conditions
├── adapters/        # 15 infrastructure adapters
├── tools/           # Domain-specific tools (coming soon)
├── daemon/          # Always-on monitoring (coming soon)
├── ui/              # TUI and web UI (coming soon)
└── cli.py           # Entry point

Configuration

All config lives in ~/.homelabcode/:

File	Purpose
config.yaml	Provider, model, permissions, adapter settings
topology.json	Discovered topology map (auto-generated)
HOMELAB.md	Your lab description (write this yourself)
credentials.json	API tokens (encrypted at rest)
memory/	Persistent agent memory
sessions/	Saved conversation sessions
extensions/	Custom extensions

HOMELAB.md

Write a description of your lab in ~/.homelabcode/HOMELAB.md. It gets injected into every query:

# My Homelab

## Network
- 10.0.0.0/24 — main LAN
- 10.0.1.0/24 — IoT VLAN

## Nodes
- pve1 (10.0.0.10) — Proxmox host, 64GB RAM
- nas (10.0.0.20) — TrueNAS, 4x4TB ZFS
- k3s1 (10.0.0.30) — k3s node

## Services
- Traefik reverse proxy on pve1
- Prometheus + Grafana on k3s1
- Home Assistant on pve1 (VM)

Commands

/discover [cidr|host]   Scan network or host
/topology               Show topology summary
/focus [node]           Set active node
/ssh [node] [cmd]       Quick SSH command
/logs [service] [N]     Tail service logs
/alerts                 List active alerts
/memory [clear]         View/clear memory
/session [list|save|load|new|branch]
/compact [N]            Clear history
/plan                   Plan mode (read-only)
/bypass                 Bypass confirmations
/doctor                 Run diagnostics
/notify [msg]           Send notification
/help                   Show commands
/quit                   Exit

Permissions

Three modes control how destructive actions are handled:

• default — destructive tools require confirmation
• plan — read-only mode, all destructive tools blocked
• bypass — no confirmations (use with caution)

Development

git clone https://github.com/slothitude/homelabCode.git
cd homelabCode
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Verify topology module
python -c "from homelab.topology import TopologyMap; t = TopologyMap(); print(t.summary())"

# Verify adapters
python -c "from homelab.adapters import ADAPTER_REGISTRY; print(sorted(ADAPTER_REGISTRY.keys()))"

Project Status

HomelabCode is in early development.

Done:

• Agent core (loop, tools, events)
• AI providers (Anthropic, OpenAI) with cost tracking
• Session management and context building
• Permission system
• Persistent memory
• Extension system with hot-reload
• Undo log
• Topology data model and discovery
• 15 infrastructure adapters
• CLI with REPL and headless mode

In Progress:

• Domain-specific tools (docker, proxmox, k8s, etc.)
• Daemon mode (passive monitoring + active reasoning)
• TUI (terminal UI)
• Web UI

License

MIT