a persistent multi-agent organization
for the self-hosted homelab
the operator architects. the swarm executes.
==> the goal
Every design choice traces back to one of those properties. Self-improving. Resilient. Multi-machine. Self-organizing. Self-documenting. These are not aspirations. They are the acceptance criteria.
==> what it is
An org chart made of AI personas with stable identity, owned scope, and memory, wired through a review chain. The operator pipes work in, reviews the result, and signs. The swarm does the rest.
==> the shape of it
Clusterstuck runs on a small fleet you own, split by how much you are willing to trust each part. Nothing sensitive lives where the internet can reach it, and the part that can be reached holds nothing worth taking.
Public, lonely, disposable. Terminates TLS, holds the mesh control plane and the obfuscated way in. Compromise it and you leak in-transit bytes and nothing else.
The trusted middle, on hardware you control. State, secrets, the git host, the build cache, the backups. Everything that matters lives here, behind the mesh.
The iron that actually serves models. Wall off the WAN, let it pull packages from the hub, and it answers nobody but the org.
One repo describes all of it. Change a line, push, and the fleet rebuilds only the machines whose definition changed, confirms each one is still alive, and rolls itself back if it is not. The operator signs; the machine does the paperwork.
==> [S] how it works
Work flows in one direction and accountability flows back the other way. A request is parsed, routed to the role that owns it, drafted, reviewed by a separate role, and only then surfaced to the operator for sign-off. Nothing reaches the trunk unreviewed.
==> what it produces
The difference between a swarm and a group chat is what is left behind. Clusterstuck leaves merged changes, written decisions, and an audit trail.
Changes land through a review gate on the trunk. The author and the reviewer are different roles.
Architectural choices are written down before they are built, so the why survives the doing.
Every merge carries the role that ran it. No anonymous writes, no untraceable changes.
A push is checked, built, switched, and confirmed from the outside. A change that breaks a machine rolls itself back.
==> why personas
Stable roles are not a gimmick. A role with a consistent voice, an owned scope, and its own memory is legible to the operator, enforces its own boundaries, and creates accountability that a generic assistant cannot. You can tell who did what, and why.
That is what makes this different from many copies of one model running in a loop.
==> where it is going
The org started as a homelab that runs itself. It is becoming a place to put things: a private cloud for the handful of people the operator actually trusts, each with their own space, their own color, and their own keys, on hardware that belongs to no one else.
Same fleet. Same swarm. A little more company.
==> built in the open
This is a real, self-hosted, multi-machine fleet running on NixOS, with a persistent multi-agent swarm doing the plumbing. It is not a demo and not a diagram. The engineering is meant to be inspectable.
Declarative NixOS fleet. Reproducible machines, built from one flake. (mirror pending)
The persistent organization: persona identities, prose, and the review chain. (mirror pending)
Built and operated by one person, with the swarm carrying the parts that are worth carrying. More at yar.sh.