Remote Builds

Remote builds let you run a Cluster session on a provisioned VM instead of your local machine. The CLI acts as a thin client — it streams input to the remote agent and receives output back over pub/sub. The VM does all the work: file operations, command execution, tool calls.

When to use remote mode

• Heavy workloads — builds, long-running tests, or tasks that would slow down your laptop
• Isolated environments — working on code you don't want touching your local system
• Shared sessions — multiple clients can attach to the same remote session

Starting a remote session

cluster remote

This opens a picker where you can select a project and target VM. The CLI then connects to the remote agent and opens the TUI.

Managing VMs

List VMs associated with your account:

cluster vm ls

Other VM subcommands:

How it works

In remote mode, the Build API (running alongside the VM) owns all message persistence. The CLI publishes user input events and subscribes to agent output events — it never writes messages directly to storage. This avoids the duplication issues that come with multiple writers.

When you disconnect, the session keeps running on the VM. Reconnect any time with:

cluster --resume

or use --attach to explicitly pick up a live session.