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.
Consequences, analysis and reuse
Read effects.json for status, pick, delegation or receiver
maintenance. status --subnet refreshes the backend registry over the network;
ordinary status may refresh an empty registry too. When chat backends exist,
status calls pick("lru") and writes the last-used state, changing a future
selection before any task runs. Consult the backend declaration
for inherited discovery effects.
Delegation sends task text to the configured receiver and rejects HTTP redirects
before forwarding task credentials, including when observation is disabled.
With an active session, its POST records transport evidence without task text,
token or response body; remote effects remain unknown. delegated: true records
an HTTP response, not verified completion of the remote task. After timeout,
reconcile receiver state before repeating a possible mutation; no request
deduplication or distributed rollback is supplied. Receiver maintenance follows
the operator's named commands and existing task authority. Saved status reports
and receiver output may retain machine details and task data.
See the common contract.
Exposed via [[llm_mcp]] as cluster_status. Related: [[llm_backends]]
(discovery), [[infra_advisor]] (per-machine tips), [[auto_router]].
