The Machineuse architecture
A distributed control plane schedules isolated browsers onto worker nodes by live load, over a brokerless NNG mesh — with systemd-nspawn container isolation and a snapshot-based dormancy lifecycle.
Machineuse has two roles: a control plane that schedules and tracks browser instances, and worker nodes that run them. They coordinate over a brokerlessNNG mesh — no external message broker. Each browser is isolated in asystemd-nspawn container, and idle instances are snapshotted to dormancy and revived on demand.
Request → schedule → NNG mesh → worker → nspawn container → dormancy lifecycle
The control plane
The control plane is the brain of the cluster. It tracks every worker node, the browser instances running on them, and the live load each node is under. When a client requests a browser, the control plane decides where that browser should run and instructs the appropriate worker to provision it. It also collects real-time metrics and reacts to failures.
Worker nodes
Worker nodes do the actual work of running browsers. Each worker runs an agent that joins the control plane over NNG and reports its capabilities and current utilization. When told to, it launches a browser inside an isolated container, keeps it healthy, and reports metrics back. Scaling out is as simple as starting another worker agent and pointing it at the control plane — scheduling adapts automatically.
Load-aware scheduling
Placement is not round-robin. The control plane schedules each browser instance bynode capability and live load, so sessions land where there is genuine capacity rather than piling onto a single overloaded host. This keeps latency predictable as the fleet grows and prevents one heavy workload from degrading everything else on a node.
Brokerless NNG mesh
Nodes communicate over a brokerless NNG (nanomsg-next-generation) mesh. There isno external message broker — no RabbitMQ, Kafka, or Redis to deploy, secure, and babysit as a single point of failure. Messaging is node-to-node, which keeps the operational surface small and removes a common bottleneck in browser-grid deployments.
systemd-nspawn container isolation
Every browser runs in its own systemd-nspawn container with a dedicated filesystem and resource envelope. systemd-nspawn is a lightweight OS-level container manager built into systemd, giving each session a clean, reproducible environment that is isolated from every other session on the same node. Untrusted pages, cookies, and state stay contained — one session cannot see or interfere with another.
Snapshot-based dormancy
Browsers are expensive to keep resident when idle. Machineuse addresses this with asnapshot dormancy lifecycle: an idle instance is snapshotted — its state persisted to a filesystem snapshot — and its live CPU and memory reclaimed for other work. When the session is needed again, the snapshot is revived on demand, restoring state without a cold rebuild. This lets a cluster hold far more logical sessions than it could keep simultaneously live.
Instance lifecycle
Request
A client asks the control plane for a browser instance with a given capability profile (image, resources, options).
Schedule
The control plane selects a worker node by capability and live load, so the session lands where there is real capacity.
Provision
The chosen worker launches the browser inside a dedicated systemd-nspawn container with its own filesystem and resources.
Run
The client drives the isolated browser. Per-node metrics stream back so the control plane always sees current utilization.
Dormancy
When an instance goes idle, it is snapshotted to dormancy — its state persisted and its live resources reclaimed.
Revival
On the next request for that session, the snapshot is revived on demand, restoring state without a cold rebuild.
Metrics & auto-healing
The control plane maintains per-node time-series metrics and watches for failures. If a worker or instance dies, failure detection triggers automatic recovery — including migrating instances so the fleet keeps running without manual intervention.
Read the full docsSource on GitHub →
Next: use cases · how it compares · FAQ