Homelab Orchestrator

Security-first control-plane skeleton for Silver, Phillip, and Samantha.

What exists

• Executable, versioned policy that separates identities and host permissions.
• Fail-closed task authorization for schema-like required fields, expiry, policy version, host boundaries, runbook enablement, risk, approval, and global mutation state.
• Local SQLite task ledger and JSONL audit log with basic credential redaction.
• Local-only HTTP control-plane endpoints: GET /healthz, GET /status, POST /tasks, and explicit Kuma snapshot endpoints.
• A signed-capability gateway reference that accepts only R-01-host-health; see gateway deployment.
• A Silver dispatcher that selects the matching Tailnet gateway from the task host and sends only a signed capability.
• Telegram long-polling primitives with numeric sender/chat authorization and a fixed command grammar; no live bot is configured.
• A local-only Silver control-plane service with a persistent task lifecycle and explicit dispatch of only R-01-host-health; see Silver deployment.
• A direct, read-only Uptime Kuma Socket.IO adapter with sanitized monitor snapshots, 60-second polling, and local down/recovery delta records; see Kuma adapter.
• A fixed, input-free host-health runbook and a hardened systemd unit, documented in the gateway installation checklist.
• Tests proving intended authorization and gateway-denial cases.

POST /tasks only authorizes and audits a request. Explicit dispatch is limited to the deployed, input-free R-01-host-health runbook through signed Tailnet gateway capabilities. There is no shell-command endpoint, Docker socket access, Telegram integration, OpenAI runtime integration, Kuma write path, or automatic remediation.

Local verification

Requires Node 22.13 or newer.

npm test
npm run check
npm start
curl http://127.0.0.1:8080/healthz

Deployment stance

The supplied compose definition binds only to loopback and starts with mutations disabled. Do not deploy it until the read-only inventory confirms runner has durable storage and a private authenticated route to primary.

Next milestones

1. Configure a private, allowlisted Telegram bot as a read-only operator surface.
2. Add a human-approved notification route for monitoring deltas.
3. Expand read-only runbooks only after per-runbook review and denial tests.
4. Run hostile-input and failure-closed tests before enabling any mutation-capable runbook.