Registering Your Own Machines as Workers: What the CLI Does for You

The ClusterCode CLI is how you register your own machines as workers. It takes a laptop, a desktop under a desk, or a rack of Linux servers from nothing to hosting DevBoxes: it checks the machine, installs and starts the container engine, signs you in, registers the machine with your tenant, and runs the worker, downloading, verifying, and updating it for you. Then it keeps that machine a good worker, which takes more than it sounds. A worker advertises the memory ceiling of its container runtime, not the memory in the box, and on Windows and macOS that runtime is a VM sized by whoever installed it, so a machine can quietly host a fraction of the DevBoxes it could while every health check passes. A VM that never returns memory starves the host instead. And its virtual disk grows with every image build and never shrinks. Here is what the CLI does, including the parts most people never find.

Getting a machine ready takes four commands. Install the CLI with npm install -g @clustercode/cli, then run clustercode login, which signs you in through your browser, or with a pasted token on a server you reach over SSH. clustercode onboard does the preparation: it runs every health check and offers to fix the failures it can, from signing in and choosing a tenant to setting up WSL2 on Windows and installing and starting the container engine with the platform's own package manager. Whatever it cannot fix is listed at the end with the command that would. Then clustercode worker starts the worker, clustercode status shows who you are and whether the machine can reach ClusterCode, and clustercode doctor runs the health checks again whenever you want to know where a machine stands.

Podman and Docker are both supported. Podman is the recommended engine on Windows and macOS for one reason: the CLI can size Podman's memory for you, while Docker's limit lives in Docker Desktop's settings or in WSL's configuration, and the CLI points you there instead of changing it. On Linux the choice makes no difference to capacity, because containers run directly on the host and nothing caps them below its memory.

One step of clustercode onboard runs even when every check passes: sizing the memory the container runtime may take. The number is a ceiling, not a reservation, and memory is only used while DevBoxes run. The wizard asks how the machine is used. A dedicated worker hands the runtime everything except a reserve for the host; a shared machine, one you also work on, caps the runtime at half its memory and keeps more back for you. Before anything is applied, it shows what that size fits: at 22.5 GiB, about ten small DevBoxes, five default ones, two large ones, or one extra large, with Windows DevBoxes needing a little more than their size. For Podman the CLI applies the change itself, says up front when that means restarting WSL, and saves the choice when it is applied. clustercode onboard --memory sets the size without the question, so you can change it later, when a desktop becomes a dedicated worker, or set it across a whole fleet in one script.

A ceiling only protects the host if the VM gives memory back. On Windows, the WSL2 VM keeps everything its guest has touched, page cache above all, charged to the host until it shuts down, unless memory reclaim is on, and even then reclaim does not always work: we have seen it accepted and doing nothing on a real Windows build. So the CLI turns reclaim on where it is off, never overrides a mode already in effect, and does not take the setting at its word. Until reclaim is proven on a machine, the CLI sizes it as if memory never comes back, leaving the host a larger reserve, and clustercode doctor reports how much memory the host actually has left, not just what the runtime was promised. On macOS the VM may hold its memory until the machine restarts, so the CLI tells you to treat the size as fully used.

Proving it takes one command, clustercode onboard --verify-reclaim, and ten minutes or more of an idle runtime. The CLI fills the VM's cache by reading the runtime's own images, never writing to its disk, then leaves the machine alone and watches from the Windows side whether that memory comes back, because any command sent into the VM would reset the idleness reclaim waits for. A run disturbed along the way, by a worker starting or the host running short, records nothing. A yes earns the machine the smaller host reserve, and the CLI offers to raise the runtime to match. The verdict is tied to the WSL version and reclaim mode it was measured under, so a WSL update asks the question again, and on a fleet, a verdict measured on one representative machine can be recorded on the others by hand.

The disk has the same shape of problem: it only grows. A WSL-backed Podman machine keeps its filesystem in a virtual disk that grows whenever containers and image builds write to it and never shrinks when they delete, so the peak of every build becomes space the host drive never gets back. On Windows, clustercode doctor shows how large that disk is on the host, how much of it is in use, and how much could be returned, and it warns only when the amount matters for that drive: 20 GB is worth reclaiming with 30 GB free, not with 500.

clustercode machine compact gives that space back. It trims the machine's free space, stops the machine and only its own WSL distribution, never every distribution on the computer, compacts the disk behind a single administrator prompt, and starts the machine again. It shows the plan and asks before stopping anything, refuses while any container is running in the machine, checking inside the machine itself rather than trusting whichever connection the host happens to use, and once it has stopped the machine it starts it again on every path: a declined prompt, a failure, a timeout, or Ctrl+C. It reports the disk's size and the drive's free space before and after.

Several of these are built for people running more than one worker. clustercode doctor --json returns the checks in machine-readable form and exits non-zero when one fails, so it works as a health gate in a script, while warnings such as a reclaimable disk never trip it. One clustercode onboard --memory script can run across a mixed fleet: machines with nothing to apply, like native Linux, succeed; a size that could not be applied, as on Docker, fails the run instead of reporting success; and without a terminal, only the explicit flag counts as consent to restart WSL.

What the CLI does not do is worth stating plainly. It cannot resize Docker's memory, can measure reclaim only for Podman on WSL, and compacts disks only for a WSL-backed Podman machine on Windows. On macOS the memory ceiling should be treated as fully used, and on a Windows build where reclaim measures as doing nothing, the size is the only lever left. We would rather you learn each of these from a health check, with the fix printed next to the warning, than from a worker that quietly did less than it could. The CLI is Apache-2.0 and on GitHub.