Machineuse
Quickstart

Deploy a browser cluster in minutes

Start with Docker Compose on a single node, create an isolated browser, then scale out to a distributed control plane and worker nodes — all self-hosted, no SaaS.

To run Machineuse, start a single-node cluster with Docker Compose, create your first isolated browser via the control plane, then scale out by starting worker agents that join over the brokerless NNG mesh. Requires a Linux host withsystemd-nspawn.

Deploy in five steps

Check prerequisites

You need a Linux host with systemd-nspawn support and Docker installed. A single machine is enough to start; a production fleet is a control plane plus one or more worker nodes.

Start a single-node cluster

Clone the repository and bring the stack up with Docker Compose. This runs the control plane and a local worker on one host so you can create browsers immediately.

Create your first browser

Ask the control plane for an isolated browser instance. It provisions a systemd-nspawn container on an available worker and returns a handle you can connect to.

Scale out worker nodes

Start additional worker agents on more machines and point them at the control plane over NNG. Scheduling adapts automatically — new sessions land on nodes with real capacity.

Observe and operate

Watch per-node metrics from the control plane. Idle browsers snapshot to dormancy on their own, and auto-healing migrates instances off failed workers.

1 · Start a single-node cluster

shell
# Clone the repository
git clone https://github.com/dotcommoners/machineuse.git
cd machineuse

# Bring up the control plane + a local worker
docker-compose up -d

systemd-nspawn is a Linux-only, OS-level container manager. On non-Linux hosts, run the cluster inside a Linux VM. See the documentation for host requirements and configuration.

2 · Create your first browser

shell
# Ask the control plane for an isolated browser instance
machineuse-cli create --image ubuntu:22.04

# List running instances and where they landed
machineuse-cli ls

3 · Scale out worker nodes

shell — on each new machine
# Join a new worker to the control plane over NNG
python -m machineuse.nodes.agent \
  worker-2 tcp://control-plane:5000

# The control plane now schedules onto worker-2 by live load

There is nothing else to deploy between nodes — the NNG mesh is brokerless, so you never stand up or secure a separate message broker.

Full installation guideSource on GitHub →

Next: how it works · all features · use cases