2.6 KiB
2.6 KiB
Homelab Butler 🤵
Unified API proxy + infrastructure management for Homelab Pfannkuchen.
Base URL: http://10.4.1.116:8888
Auth: Authorization: Bearer <BUTLER_TOKEN>
Service Proxy
Proxies requests to backend services with automatic authentication:
| Service | Backend | Auth |
|---|---|---|
dockhand |
10.4.1.116:3000 | Session |
sonarr |
10.2.1.100:8989 | API Key |
radarr |
10.2.1.100:7878 | API Key |
seerr |
10.2.1.100:5055 | API Key |
outline |
10.1.1.100:3000 | Bearer |
n8n |
10.4.1.113:5678 | X-N8N-API-KEY |
proxmox |
10.5.85.11:8006 | PVE Token |
homeassistant |
10.10.1.20:8123 | Bearer |
grafana |
10.1.1.111:3000 | Bearer |
uptime |
159.69.245.190:3001 | Bearer |
waha |
10.4.1.110:3500 | API Key |
forgejo |
10.4.1.116:3001 | Bearer |
semaphore |
10.4.1.116:8090 | Bearer |
Usage: GET/POST/PUT/DELETE /{service}/{path}
VM Lifecycle
| Endpoint | Method | Description |
|---|---|---|
/vm/list |
GET | All VMs across all 7 Proxmox nodes |
/vm/create |
POST | Full VM deployment (~10 min): ISO build, VM create, SSH wait, inventory, Ansible |
/vm/status/{vmid} |
GET | VM status (CPU, RAM, uptime) |
/vm/{vmid} |
DELETE | Destroy VM |
POST /vm/create
{"node": 5, "ip": "10.5.1.115", "hostname": "lychee", "cores": 2, "memory": 4096, "disk": 32}
Steps: iso-builder → Proxmox VM → wait SSH → add to pfannkuchen.ini → Ansible base setup (Docker, Borgmatic, Hawser)
Ansible / Inventory
| Endpoint | Method | Description |
|---|---|---|
/inventory/host |
POST | Add host to pfannkuchen.ini (idempotent, with group) |
/ansible/run |
POST | Run Ansible playbook on host |
POST /inventory/host
{"name": "lychee", "ip": "10.5.1.115", "group": "auto"}
TTS / Speech
| Endpoint | Method | Description |
|---|---|---|
/tts/speak |
POST | Text-to-speech via Chatterbox |
/tts/voices |
GET | Available voices |
/tts/health |
GET | Speaker + Chatterbox status |
POST /tts/speak
{"text": "Hallo!", "target": "speaker"}
"target": "speaker"→ plays on Pi5 speaker (10.10.1.166)"target": "telegram"→ generates OGG on hermes, useMEDIA:/tmp/trulla_voice.ogg
Credentials
Reads from Vaultwarden cache (synced by host cron) with flat-file fallback (/data/api/).
Stack
docker compose build && docker compose up -d
Requires:
.envwithBUTLER_TOKEN/app-config/kiro/api/flat-file credentials- SSH key mount (
/home/sascha/.ssh:/root/.ssh:ro) for VM operations