Cloud Sessions: Run Coding Workloads on Remote Machines

A cloud session is a standard session where the coding workload executes on a different machine. It shows up in the sidebar, feeds into chat, and preserves its transcript just like a local one. The Gateway continues to own the conversation, the reconciled workspace, model credentials, and placement records, while commands, file modifications, and tool operations run elsewhere. Should the remote machine vanish, the session and its persistent state remain intact; how it picks up again depends on the destination. Cloud workers get replaced automatically upon the next message, whereas an offline paired device holds its placement and waits for the device to come back.

Sessions can operate in three locations, all sharing the same session, chat, and Place picker:

For every remote placement, model inference remains proxied through the Gateway, so provider credentials never touch the remote machine, and finished work syncs back into the session's managed worktree. Both the OpenClaw runtime (worker-turn) and Codex (remote-exec) support these same destinations.

Paired devices: your own hardware as session hosts

Pair any machine with a single pasted command, then enable it for session hosting:

openclaw connect <join-url> --service --session-host

The device keeps an outbound connection to the Gateway, announces worker slots (one per CPU core by default, adjustable via nodeHost.workerRuns.capacity), and can run each hosted session inside a Docker-compatible container if desired (nodeHost.workerRuns.isolation: "container"). When a device goes offline, its active placement is preserved, and the session waits for reconnection rather than losing any work.

The node host reconnects after temporary transport loss. A worker child gets a limited 120-second admission window. If that window lapses before the turn starts, the Gateway may launch another child, capping at five attempts total (roughly ten minutes plus backoff), within the original turn timeout. Launch retries follow exponential backoff with jitter, and each attempt logs its own terminal result and reason in the node launch journal. Credential and build rejections are terminal, and work that has already begun is never replayed under this policy.

If a journal-terminal worker has released its turn claim but teardown is stuck, stuck-session recovery logs the turn failure after a 30-second cleanup grace period, on the next diagnostic cycle. Live workers and turns still holding their claims remain unaffected. After a Gateway restart, orphan workspace cleanup for failed placements runs in the background once readiness is reached; ownership fencing and pending workspace-result recovery still execute before readiness.

Refer to Nodes for pairing, capacity, isolation, and offline behavior, and Connect for the CLI.

Cloud workers: rented machines through Crabbox

Set up a profile under cloudWorkers.profiles, and the bundled Crabbox plugin provisions machines on demand across cloud backends (AWS, Hetzner, and others), executes your setup command, enrolls the box as a temporary node, and removes everything when the session ends. The machine is disposable by design: no standing credentials reside on it, and the durable state stays with the Gateway.

Check Cloud Workers for profiles, requirements, dispatching, moving sessions between destinations, and the security model.

Automatic load balancing across devices

There is no need to choose a device manually. Selecting Any available node in the Place picker, or dispatching with autoDevice: true, automatically picks a paired session host and retries up to three ranked hosts if provisioning fails before a machine is allocated. OpenClaw worker-turn placements rank hosts by most free worker slots, breaking ties by device ID; Codex remote-exec placements do not use worker slots, so eligible hosts are ranked by device ID alone. When no host qualifies, the error explains precisely why: no session hosts paired, all disconnected, or all at capacity.

See Nodes for the selection rules and Control UI for the picker.

Sleeping and waking: idle suspension and warm images

Two profile settings convert cloud workers from always-on machines into compute that sleeps when idle:

• suspendAfter: "2h", after the session has been idle for the duration, the Gateway performs the same safe stop as Stop cloud worker…: it reconciles the workspace first, then releases the machine. While suspended, you pay for retained snapshot storage only. The next message provisions a replacement automatically, with no button to press.
• settings.warmImage: true, capture a scrubbed machine image when a worker stops, and start later workers for the same profile from that image instead of provisioning cold. Paired with suspendAfter, a suspended session wakes on a warm machine in a fraction of the cold provisioning time.

Suspension never interrupts work: sessions with an active turn, queued messages, or unreconciled results are skipped and re-checked on the next sweep. See the profile fields in Cloud Workers for costs, capture boundaries, and prerequisites.

What stays with the Gateway

Placement is disposable; the session is not. The transcript, the last-reconciled workspace files, placement history, and every provider credential live with the Gateway in all placements. A dead cloud machine or an idle suspension resolves automatically: the session remains in your sidebar, and the next message provisions a replacement, warm when an image exists, cold otherwise. An offline paired device is different by design: the placement stays active and waits for the device to reconnect, and Continue on Gateway… is an explicit action that can lose unsynced device files. Workspace changes made after the last reconciliation are the only loss window, and clean stops (including auto-suspension) reconcile before releasing the machine.

Related

• Cloud Workers, profiles, dispatch, moves, security model
• Nodes, pairing, session hosting, capacity, container isolation
• Control UI, the Place picker and session badges
• Connect, one-command device onboarding
• Managed worktrees, the workspace cloud sessions reconcile into
• Sandboxing, reducing blast radius for local execution instead