Phase 1 · MVP in development

// Docker simplicity. Kubernetes compatibility.

Run Kubernetes Pod YAML on plain Docker.

Clustro is one binary that turns a handful of Docker machines into a cluster. No etcd, no CRI, no network plugins. Built for teams running 22 nodes or fewer.

install on every machine

$ curl -sfL https://getclustro.in/install.sh | sh

01Requirements

What	Supported
Operating system	Linux or macOS
CPU architecture	`amd64` or `arm64`
Container runtime	Docker Engine 24 or later, running and reachable by your user. On macOS, Docker Desktop, Colima, OrbStack and Rancher Desktop all work.
Network	Machines on the same subnet can find each other automatically. Otherwise, pass `--leader` to `join`.
Ports	`7443` on the leader (API), `7444` on every node (agent)

Clustro does not install Docker for you. If docker version doesn't work, follow the Docker install guide first.

02Install the clustroctl binary

Run this on every machine that will be part of the cluster, and on any laptop you want to drive the cluster from.

bash

$ curl -sfL https://getclustro.in/install.sh | sh
Downloading clustroctl v0.1.0 for linux/amd64...
Checksum verified.
Installed clustroctl v0.1.0

The script detects your OS and CPU, checks Docker, downloads the matching release, verifies its SHA-256 checksum, and installs it to /usr/local/bin/clustroctl. It asks for sudo only if it can't write there.

Prefer to read before you pipe to a shell? Download it first:

bash

$ curl -sfL https://getclustro.in/install.sh -o install.sh
$ less install.sh
$ sh install.sh

Check it worked:

bash

$ clustroctl version

03Create a cluster

Pick one machine to be the leader. It runs the API, the scheduler and the state store, and it can run pods too.

leader · linux

$ sudo clustroctl init
✔ Docker 27.1.1 detected
✔ Cluster "clustro-office" created
✔ Leader running at https://10.0.0.10:7443
✔ Admin credentials written to ~/.clustro/config

Join other machines on this network with:
  clustroctl join --token clustro.a1b2c3.9f8e7d6c5b4a3f2e

Installs the clustro-leader systemd service and keeps state in /var/lib/clustro.

leader · macos

# no sudo on macOS: it runs as your user so it can reach Docker Desktop
$ clustroctl init
✔ Docker 27.1.1 detected
✔ Cluster "clustro-office" created
✔ Leader running at https://10.0.0.10:7443

Join other machines on this network with:
  clustroctl join --token clustro.a1b2c3.9f8e7d6c5b4a3f2e

Installs a launchd agent for your user and keeps state in ~/.clustro.

The join token is valid for 24 hours and any number of joins. Need another one later? Run clustroctl token create on the leader.

04Join more machines

On every other machine, run the command init printed. It finds the leader on the local subnet by itself.

worker

# Linux: prefix with sudo. macOS: run as your normal user.
$ sudo clustroctl join --token <token>

On a different network, or if discovery is blocked, point it at the leader directly:

worker

$ sudo clustroctl join --leader 10.0.0.10 --token <token>

Then, back on the leader, check that everyone showed up:

leader

$ clustroctl get nodes

05Deploy your first Pod

Write an ordinary Kubernetes Pod manifest. Nothing Clustro-specific in it.

web.yaml

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  containers:
    - name: nginx
      image: nginx:1.27
      ports:
        - containerPort: 80
          hostPort: 8080
      resources:
        requests: { cpu: 100m, memory: 64Mi }

bash

$ clustroctl apply -f web.yaml
$ clustroctl get pods -o wide
NAMESPACE  NAME  READY  STATUS   RESTARTS  AGE  NODE      IP         PORTS
default    web   1/1    Running  0         2m   worker-2  10.0.0.12  8080->80/tcp
$ curl http://10.0.0.12:8080

Fields Clustro doesn't support yet are rejected with a clear error, never silently ignored, so you always know what's actually running.

Everyday commands

clustroctl get pods -w

Watch pods as they change.

clustroctl logs web -f

Follow a pod's logs.

clustroctl describe pod web

Full details and recent events.

clustroctl delete pod web

Stop and remove a pod.

clustroctl status

Leader, node and pod counts, warnings.

clustroctl backup -o state.db

Snapshot the cluster while it runs.

06Install options

Set these environment variables before running the installer. Note that they go on sh, not on curl:

bash

$ curl -sfL https://getclustro.in/install.sh | CLUSTRO_VERSION=v0.1.0 INSTALL_DIR=$HOME/.local/bin sh

Variable	Default	What it does
`CLUSTRO_VERSION`	latest	Install a specific version.
`INSTALL_DIR`	`/usr/local/bin`	Where to put the binary.
`CLUSTRO_SKIP_DOCKER_CHECK`	`0`	Set to `1` to install without Docker, for a laptop that only runs the CLI.
`CLUSTRO_RELEASE_URL`	`https://getclustro.in/releases`	Download from a mirror instead.

Shell completion

zsh

$ clustroctl completion zsh > "${fpath[1]}/_clustro"

07Uninstall

clustroctl reset stops the service, removes the pod containers and volumes, then deletes the state directory. Run it on each machine.

bash

$ sudo clustroctl reset
$ sudo rm /usr/local/bin/clustroctl

reset on the leader deletes the cluster's state. Take a clustroctl backup first if you might want it back.