zedarvates cluster — the homelab as one schedulable resource
Idle local capacity is recovered cost. Instead of always hitting the same backend (or the cloud), spread work across every reachable machine.
python -m skills.cluster.cli status --subnet # all machines + recommended target
python -m skills.cluster.cli pick --strategy lru # spread to the idlest machine
python -m skills.cluster.cli pick --strategy latency
python -m skills.cluster.cli delegate 192.168.1.38 "restart the model server"
How it routes
- status groups discovered backends (LM Studio, Ollama, LocalAI, ComfyUI, Qdrant…) by host → the cluster view, with latency and the recommended target.
- pick
lruchooses the least-recently-used capable chat backend, so the next task lands on an under-used box — work spreads across the cluster. - pick
latencychooses the most responsive backend.
Delegation (hand-off only)
delegate(host, task) POSTs {"task": …} to a machine's agent endpoint
(BOTTE_AGENT_<host> env or --url). The endpoint host must match host;
non-loopback delegation requires HTTPS and a token from
BOTTE_AGENT_TOKEN_<host> or BOTTE_AGENT_TOKEN. It never runs privileged maintenance
itself — wire a trusted agent (e.g. Hermes, which has the rights to do simple
machine maintenance) on each box to receive and execute tasks. No endpoint
configured → safe no-op that tells you how to wire one.
Security: elevated-rights machine maintenance stays in your agent on each machine; botte only routes and hands off. The bundled HTTP receiver is for loopback use; expose it on a LAN only behind a trusted HTTPS reverse proxy.
Reference machine-agent (deploy on each box)
Until your agent (Hermes) exposes an endpoint, run the bundled receiver — it
accepts delegated tasks safely: a whitelist of named read-only actions
(ping, machine_status, disk, local_backends), never arbitrary shell,
loopback by default, token-gated for any non-loopback bind. Privileged
maintenance handlers are deliberately absent until you scope the policy.
python -m skills.cluster.agent serve --token "$BOTTE_AGENT_TOKEN"
# then from the cluster:
python -m skills.cluster.cli delegate 127.0.0.1 machine_status --url http://127.0.0.1:8799/task
Privileged maintenance (operator-approved, confirm-gated)
To let the cluster trigger real maintenance (restart a model server, pull/update
a model, clear a cache), the operator pre-approves a named whitelist on each
machine — the remote caller can only trigger commands by name and must pass
confirm: true. There is no arbitrary shell from the network.
# operator, on the machine (example: examples/cluster/maintenance-commands.json)
python -m skills.cluster.agent serve --host 0.0.0.0 --token "$BOTTE_AGENT_TOKEN" --commands examples/cluster/maintenance-commands.json
# caller: list what's permitted, then run with confirmation
# {"task":"list_commands"}
# {"task":{"action":"run","args":{"name":"restart_ollama","confirm":true}}}
Defaults are safe: with no --commands file, no maintenance is possible —
only the read-only actions. Maintenance on a non-loopback bind requires a token.
Exposed via [[llm_mcp]] as cluster_status. Related: [[llm_backends]]
(discovery), [[infra_advisor]] (per-machine tips), [[auto_router]].