clustercode onboard

Usage

clustercode onboard

Description

An interactive wizard that walks you through the complete setup:

1. Runs all health checks (same as clustercode doctor)
2. For each failure, offers to fix it:
   • Not logged in → runs the login flow
   • Worker not configured → runs tenant selection
   • WSL2 missing (Windows) → installs WSL2 and Ubuntu distro
   • container runtime missing → installs and starts Podman
   • Orchestrator unreachable → shows configuration guidance
3. Offers to size the container runtime’s memory and, for Podman on the WSL backend (WSL 2.0+), turns memory reclaim on where it’s off — then offers to measure whether it works — see below
4. Re-runs all checks to verify fixes

Options

Flag	Description
--memory <mb>	Set the container runtime’s memory allocation, in MiB (see below)
--verify-reclaim	Measure whether the runtime returns memory to the host (10 minutes or more; keep the runtime idle), and record the result. Podman on the WSL backend only (see below)

--memory skips the sizing questions either way. In a script or CI (no TTY) it also applies the change without prompting, and is the only way to apply a change non-interactively — a stored RUNTIME_MEMORY_MB value alone is deliberately not treated as consent. In an interactive terminal it still asks you to confirm before applying, because on Windows the change restarts every WSL distribution.

Sizing the container runtime’s memory

This step runs even when every other check already passes — an under-provisioned runtime doesn’t fail health checks, it just quietly caps how much work this worker can be given. Values are in MiB (1024-based) — 8192 means 8 GiB. The MB in RUNTIME_MEMORY_MB and --memory is historical; the CLI displays GiB throughout.

If nothing has been configured yet, the wizard asks how the machine is used:

• Dedicated worker — mostly hosts DevBoxes. Gets everything except a preset reserve of 6 GiB — but that smaller reserve applies only once the VM has been measured giving memory back on this machine, with --verify-reclaim or by hand. Reclaim being on is not enough: until there’s a verdict, the preset leaves max(8 GiB, 25% of RAM) behind instead. The same goes everywhere the feature can’t exist at all (macOS, Hyper-V, WSL older than 2.0), and always for Docker, whose VM the CLI can’t measure — so Docker is sized as if reclaim does not work even with reclaim on. Nothing is reserved on Linux, which has no VM in the way.
• Shared — you also work on this machine day to day. Capped at half the host, with a larger preset reserve of 12 GiB on Windows/macOS so the desktop stays usable — the same figure with or without memory reclaim.

These preset reserves are deliberately conservative and are not the hard limit. A custom amount may go higher, up to the safe ceiling, which leaves less behind — 4 GiB on Windows, 6 GiB on macOS.

It then prints a fit table for the chosen amount before asking you to confirm. Each count first subtracts a host reserve — max(2 GiB, 5% of the runtime memory) — from the total, then divides what’s left by that row’s size:

  2 GiB (small)         fits ~10
  4 GiB (default)       fits ~5
  8 GiB (large)         fits ~2
  16 GiB (extra large)  fits ~1
Counts are per size — mixed sizes share the same pool.
Windows DevBoxes need ~2 GiB more than their size, so fewer fit than shown.

These counts are estimates at each size — actual capacity depends on what you launch, and a DevBox running a graphical session should budget one size up. The Windows note matters: a Windows DevBox needs roughly 2 GiB more than its stated size to run, so don’t read “fits ~5” as five Windows DevBoxes without adjusting for that.

Pass --memory to skip the sizing questions and set an exact value (also honored when a fresh container-runtime machine is created). Interactively you are still asked to confirm before it applies, since applying it restarts every WSL distribution on Windows; without a TTY (CI, scripts) it applies immediately — this is the only way to apply a change non-interactively:

clustercode onboard --memory 24576

The allocation is a ceiling, not a reservation — it caps what the runtime can take rather than setting it aside up front. That is not the same as the memory coming back, though, and onboard says which case you’re in before it asks you to pick a number. On Windows that note is one of seven:

This is a ceiling, not a reservation — memory is used while DevBoxes run and returned to Windows while the runtime is idle.
Memory reclaim is configured but has not been verified on this machine — this number is sized as if it does not work; run `clustercode onboard --verify-reclaim` to check.
Memory reclaim is in dropcache mode, which cannot be verified on this WSL version — this number is sized as if it does not work.
Memory reclaim does not return memory on this Windows build, so treat this number as fully used.
The Podman machine runs on Hyper-V, not WSL, and holds the whole amount while it runs, so treat this number as fully used.
Could not read the WSL version, so memory reclaim cannot be counted on — treat this number as fully used.
Without memory reclaim (WSL 2.0+), the runtime keeps everything it has touched until `wsl --shutdown`, so treat this number as fully used.

Only the first — reclaim measured and working — is a ceiling the VM hovers below. The third is for dropCache mode on WSL older than 2.9.8, which can’t be measured (see below). The fifth is for a Podman machine on Hyper-V, which has no reclaim setting and holds its whole allocation. On macOS the VM doesn’t release memory until it restarts, so treat the ceiling as fully used there too. See It’s a ceiling, not a reservation.

Verifying that memory reclaim works

--verify-reclaim measures whether the WSL2 VM actually hands memory back, rather than trusting that the setting does what it says. It loads the VM’s page cache by reading up to 4 GiB of the runtime’s own image data (so it consumes no disk), then leaves the machine alone and watches the VM from the Windows side for up to twelve minutes. A yes needs Windows to actually get the memory back, not just the VM to shrink:

clustercode onboard --verify-reclaim

It runs only for Podman on the WSL backend, with memory reclaim on, once the runtime memory step has completed, and with an idle runtime — with containers running, or a ClusterCode worker running on the machine, it declines rather than measuring your workload instead of your machine. Anything else (Docker, a Hyper-V backend, reclaim switched off, a WSL version it can’t read) is refused with the reason, and nothing is recorded. Docker in particular is never measured: the CLI can’t see into its VM, so Docker is always sized as if reclaim does not work.

Nor is dropCache on WSL older than 2.9.8, which includes a .wslconfig that doesn’t set the key. There WSL drops the cache only after about 10 idle minutes, and only once per idle period, so a run couldn’t tell “not yet” from “never”. onboard doesn’t offer the measurement in that case, and --verify-reclaim refuses:

Memory reclaim is in dropcache mode, and on this WSL version (older than 2.9.8) WSL drops the cache only after about 10 idle minutes, and only once per idle period, so this CLI cannot measure it reliably. Nothing was measured or recorded, and the runtime stays sized as if reclaim does not work.

--verify-reclaim also refuses gradual there when the Podman machine can’t write /sys/fs/cgroup/memory.reclaim (WSL then falls back to dropCache), or can’t be asked. See dropCache before WSL 2.9.8.

Allow 10 minutes or more, as the prompt below says: loading the cache comes first, so a run can take well over twelve minutes.

The result is recorded as RUNTIME_RECLAIM_VERIFIED, stamped with the WSL version and reclaim mode it was measured under, and it’s what unlocks the 6 GiB Dedicated reserve. Upgrade WSL or change the mode, and the verdict stops applying: the runtime is sized as if reclaim does not work until you measure again, which doctor suggests.

You don’t have to remember the flag. Right after onboard turns reclaim on — the one moment the answer changes what you should do next — it offers the measurement itself:

Verify that memory reclaim works on this machine now? Takes 10 minutes or more; the runtime must stay idle.

Decline, and it tells you the ceiling that a machine sized for no reclaim should use (Sized as if reclaim does not work, the ceiling for this machine is 23552MB.). Accept, and if the answer is yes, onboard offers to hand the runtime the memory it just earned:

Reclaim verified — raise the runtime to 25 GiB?

A run can also come back inconclusive — for example when the runtime hasn’t pulled enough images to fill a meaningful amount of cache, Windows ran short of memory during the run and trimmed the VM itself, or a ClusterCode worker started during the run. Nothing is recorded in that case, so the runtime stays sized conservatively and you can try again later. Full details in Verifying it works on your machine.

After a successful apply, onboard stores the value it applied as RUNTIME_MEMORY_MB, which is what stops doctor from treating that size as an install default and suggesting a different one.

Windows: this restarts every WSL distribution

On Windows, Podman runs inside a WSL2 VM, and Podman’s own memory settings don’t work there — podman machine set --memory errors, and passing --memory to podman machine init is silently ignored. The real control is the [wsl2] memory= setting in %UserProfile%\.wslconfig, a file WSL reads for every distro on the machine, not just ClusterCode’s. onboard edits it for you (preserving comments and other keys, and keeping a .bak copy the first time), then runs wsl --shutdown to apply it — which restarts all of your WSL distributions, not only the one Podman uses. Save work in other WSL sessions before confirming the change.

Where memory reclaim is off (disabled, or unset or unrecognised on WSL older than 2.1.3), onboard also sets [experimental] autoMemoryReclaim=gradual in the same write, so the VM hands memory back to Windows instead of holding everything it has touched. It leaves the key alone where reclaim is already on, including WSL’s own default from 2.1.3. On a machine whose allocation is already correct, onboard offers that entry on its own — and because .wslconfig is only read when the VM starts, even a reclaim-only change restarts every WSL distribution just the same.

Windows + Docker: onboard doesn't apply this for you

With Docker as the engine, onboard never edits .wslconfig or touches Docker Desktop settings — it only tells you where the setting lives. On Docker Desktop’s WSL2 backend, that’s [wsl2] memory= in %UserProfile%\.wslconfig, the same file described above; on its Hyper-V backend, it’s Docker Desktop’s own Resources settings. Either way, set it yourself. On the WSL2 backend you can set [experimental] autoMemoryReclaim by hand too (from WSL 2.1.3 reclaim is on unless it says disabled), which onboard likewise won’t write for you — but the CLI can’t verify it for Docker, so size Docker’s memory as if reclaim does not work.

The 2048 MiB floor accepted by RUNTIME_MEMORY_MB and --memory is a hard minimum, not a usable recommendation — hosting even one default 4 GiB DevBox needs roughly 6 GiB once the host reserve is subtracted.

See Sizing container runtime memory for the full guide, including the platform ceilings and how this interacts with RUNTIME_MEMORY_MB.

What onboard doesn’t cover

onboard prepares the machine. It does not sign your agents in, and it does not store your service access tokens — both are done in the dashboard, per worker:

• Agent sign-in — lets the agent think
• Service access tokens (GitHub / Azure DevOps / GitLab) — let the agent reach your code. Set under Settings → Environment Variables → Service access

A worker that passes doctor can still fail its first run without these. A missing source-provider token is the most common cause of a failed first run on a new setup.

When to Use

• First-time setup on a new machine
• After clustercode doctor reports failures
• When you want a one-command setup instead of running individual commands

Difference from doctor

	doctor	onboard
Checks health	✓	✓
Fixes issues	Prompts to run onboard	Fixes directly
Interactive	Yes (prompts on failure)	Yes
Idempotent	Yes	Yes

Both are safe to run multiple times. onboard is the fix; doctor is the diagnosis.