CLIO Coder
GitHub Install CLIO Coder
Menu
All tutorials

Remote workers11 min read

Work from a laptop with remote workers

Use a local CLIO Coder session to coordinate SSH workers when your machines share the required project path, runtime version, and approved access.

Written for
v0.8.0
Works in
Terminal · Desktop alpha
Basis
Documented workflow
Updated
Terminal Settings open on Workers with Add SSH node selected under Machines: automatic routing, the ready local node, Tailscale discovery, workers at once, and fleet retry and tool limits.
Settings: worker routing, machines, and limits under Workers. Terminal · v0.8.0
On this pageBefore you start Choose where each part runs Add one SSH node Install the exact client build Prepare and verify the project Choose the first worker Return edits from an independent checkout Follow the result On a cluster

Your conversation can stay on your laptop while a worker runs tools on another machine. Register an SSH node, install the exact CLIO Coder build if needed, verify its project and model route, then choose where the first bounded task runs.

Before you start

  • Noninteractive SSH access to a machine you may use for work.
  • CLIO Coder on the node at exactly your client's version. For an automatic install, the node needs Node.js 22.19 or newer and npm on its noninteractive SSH PATH.
  • The project at the same absolute path on the client and node, using shared storage or matching clean Git checkouts.
  • A model route the worker can reach from the node.

Choose where each part runs

One remote task

  1. Your laptop

    Session

    The conversation, your approvals, and the dispatch.

  2. SSH dispatch

    Fleet node

    Worker

    Runs at default authority in the same absolute project path.

  3. model requests

    The worker's route

    Inference

    A localhost address resolves on the node, not on your laptop.

The conversation stays on your laptop, the worker runs its tools on the node, and the worker's model route resolves from the node.

Worker placement and inference are separate. A local worker calling a remote model endpoint runs tools locally. An SSH worker runs tools on the selected node. A target URL containing localhost refers to the worker's machine.

Choose a node for the compiler, filesystem, data or capacity the task needs. Declared labels such as gpu help describe it, but they do not prove observed hardware or available memory. A remote worker using a cloud target can send model input to that provider under the existing information policy.

Add one SSH node

From your project root, register an SSH alias, hostname or address:

Shell

clio-coder fleet nodes add build-node --host build-node --max-workers 1
clio-coder fleet nodes list

The implicit local node already exists. Adding a node keeps unpinned work local. The new node starts as not checked.

Use an existing SSH alias to select the user, port and identity. You can also pass --user, --port and --identity-file explicitly. --labels cpu,build adds operator declarations. Start with one slot until you know the node's workload and resource limits.

In the terminal, /settings fleet opens the Workers area; choose Add SSH node under Machines. The guided flow asks for a name and host, then offers to test and record readiness or preview an install. Open a node row to see evidence and timestamps, test it, preview an install or remove its saved entry. A test started here always records its result.

Terminal Settings open on Workers with Add SSH node selected under Machines: automatic routing, the ready local node, Tailscale discovery, workers at once, and fleet retry and tool limits.
Settings: worker routing, machines, and limits under Workers. Terminal · v0.8.0

Use a LAN endpoint or optional Tailscale discovery

If the client and node share a network, prefer a LAN endpoint you have verified with SSH. Otherwise, a reachable Tailscale address or MagicDNS name can use the same worker transport.

Shell

clio-coder fleet nodes discover
clio-coder fleet nodes add travel-node --host travel-node.example-tailnet.ts.net

Discovery is opt-in. It reads tailscale status --json when the CLI is installed and signed in, lists MagicDNS names and IP addresses, and leaves the selection to you. The TUI's Discover with Tailscale lets you pick an endpoint and name the node. A discovered peer has no proven SSH access, runtime or project readiness. You can add an SSH host directly without Tailscale.

The endpoint can matter substantially. In one measurement on this project's development network, a 4 MiB SSH transfer ran at about 173 MiB/s over LAN and 1.4 MiB/s over Tailscale. SSH setup and existing connection multiplexing affect those numbers; measure your own route. CLIO Coder uses the host you configure and does not automatically switch between addresses.

Install the exact client build

If the node lacks a matching CLIO Coder runtime, preview a user-level install:

Shell

clio-coder fleet nodes install build-node

Review the package size, digest and destination. Then execute it:

Shell

clio-coder fleet nodes install build-node --yes

CLIO Coder packs the build the client actually runs, transfers it over SSH, checks its SHA-256 digest, and installs it under the node's ~/.local/share/clio-coder/workers/<digest>/. The install uses the node's existing Node.js and npm, verifies the version and updates the saved worker entry. The installer does not require sudo or modify services or shell profiles. Optional SDK dependencies are omitted.

You can also manage CLIO Coder yourself, for example with the standard installer on a cluster login node, whose private Node.js is not on PATH. The default invocation is clio-coder worker. A custom --entry that ends in worker is checked through its base command's --version; any other entry needs an explicit --version-command. The version check is never skipped.

Prepare and verify the project

Choose one supported arrangement:

Arrangement What CLIO Coder verifies Available work
Shared storage at the same absolute path A transient client-side file challenge is visible from the node. Read-only and mutating workers use that storage.
Independent checkout at the same absolute path Both trees are clean, have the same Git HEAD and matching root history. Read-only work; mutations through an isolated task worktree and SSH commit return.

CLIO Coder does not clone an arbitrary repository, map different paths, install project dependencies or stage datasets. Prepare those yourself. For independent checkouts, update both to the same clean baseline before testing.

  1. Observe first

    Shell

    clio-coder fleet nodes test build-node
clio-coder doctor

    These commands observe the node without creating directories there or granting new dispatch eligibility. A plain test can identify a clean matching checkout; recording also permits the transient client-side challenge that proves shared storage.

    Model facts distinguish network reachability, access to the model listing, model presence and runtime support. Unknown remains unknown; a catalog listing is not a successful generation or proof of a resident model.

    Each registered node adds a fleet node <id> row to doctor with its host, remote version and project check. The recording shows the report on a fresh install, before any node or model is added; each warning names the command that clears it.

    Terminal doctor report on a fresh npm install of CLIO Coder 0.8.0: a WARN that no model target is configured yet, OK rows for the version, install method, Node.js, directories, credentials, migrations, local worker capacity, toolchain, store and shell sandbox, INFO rows for optional tools that are not installed, and a WARN that the pane host is not installed.
    doctor --fix creates a fresh install's state; doctor then passes every check except the model target and the pane host, and names the command that adds each. Terminal · v0.8.0 Recording · 0:08
    Transcript
    CLIO Coder doctor on a fresh install
Recorded with CLIO Coder 0.8.0. Each section is the terminal screen at that moment.

== repaired

OK   Clio Coder version     0.8.0
OK   install method         npm (/opt/clio-coder/lib/node_modules/@iowarp/clio-coder; npm global; follows latest through npm; update after exit off (prefix not user-writable))
OK   node version           v24.20.0
OK   platform               linux-x64
OK   engine runtime         ready
OK   directory layout       config, data, state, and cache roots are absolute, distinct, and non-nesting
OK   config dir             /home/researcher/.config/clio-coder
OK   data dir               /home/researcher/.local/share/clio-coder
OK   state dir              /home/researcher/.local/state/clio-coder
OK   cache dir              /home/researcher/.cache/clio-coder
OK   state dir mode         tightened to 700
OK   data dir mode          tightened to 700
OK   settings.yaml          /home/researcher/.config/clio-coder/settings.yaml
OK   credentials            600
OK   state metadata         0.8.0 (repaired 2026-11-13T00:17:01.419Z)
OK   lifecycle migrations   9 registered, all recorded
OK   session store          /home/researcher/.local/state/clio-coder/sessions (no sessions recorded)
INFO telemetry              mode standard; research capture off; 0 workspace consents recorded
OK   installation files     build outputs present
OK   local worker capacity  24 usable CPUs, 19.7 GiB available memory; 8 local workers (built-in safety cap). GPU/VRAM and model fit are not checked.
OK   state storage          121 B (121 bytes); largest contributor home.json at 121 B (121 bytes)
OK   home storage           config 8.3 KB, data 0 B, cache 0 B
OK   interop pi             version unknown (no ACP recipe) at /opt/node/bin/pi
INFO external tool asciinema not found (install with `clio-coder tools install asciinema`)
WARN external tool herdr    pane host 0.9.5 is not installed; run `clio-coder panes install`
OK   external tool yazi     experimental integration disabled by settings
INFO external tool croc     not found (install with `clio-coder tools install croc`)
INFO external tool cliamp   not found (install with `clio-coder tools install cliamp`)
OK   files pane profile     disabled by settings
OK   pdf attachments        /usr/bin/pdftotext: pdftotext version 24.02.0; pdfinfo /usr/bin/pdfinfo
OK   toolchain              found: cc, c++, gfortran, mpicc, mpicxx, mpirun, cmake, make, python3; not on PATH: clang, nvcc, ninja, meson, sbatch
INFO slurm mcp              not set up: clio-kit, sbatch, and squeue are not on PATH and no mcp.yaml declares the Slurm server; see docs/guide/slurm.md
OK   store backend          local (no selection; the default)
OK   store root             /home/researcher/.local/share/clio-coder/store (not created yet; 420.5 GiB free at /home/researcher/.local/share/clio-coder)
OK   panes mode             Clio's private pane host opens with bare `clio-coder`; this command is not running inside one
OK   panes layout           off
OK   naming                 clean: immutable history, git refs, worktree markers
OK   validation contract    none at the workspace root; rigor default normal
OK   shell sandbox          default-autonomy shell commands run in the bwrap sandbox; writable roots: /home/researcher, /tmp, /var/tmp, /home/researcher/.cache/clio-coder/sandbox-cache; 7 secret files in the workspace and scratch roots are masked; unix sockets: a seccomp filter refuses new AF_UNIX sockets (socketpair still works) and the kernel keyring calls; yolo runs contained in the same sandbox
17 rows folded; `clio-coder doctor --verbose` prints each one
~ $

== healthy

~ $ clio-coder doctor
WARN chat                   cannot run yet: no model target is configured; run `clio-coder configure` to choose one
OK   Clio Coder version     0.8.0
OK   install method         npm (/opt/clio-coder/lib/node_modules/@iowarp/clio-coder; npm global; follows latest through npm; update after exit off (prefix not user-writable))
OK   node version           v24.20.0
OK   platform               linux-x64
OK   engine runtime         ready
OK   directory layout       config, data, state, and cache roots are absolute, distinct, and non-nesting
OK   config dir             /home/researcher/.config/clio-coder
OK   data dir               /home/researcher/.local/share/clio-coder
OK   state dir              /home/researcher/.local/state/clio-coder
OK   cache dir              /home/researcher/.cache/clio-coder
OK   settings.yaml          /home/researcher/.config/clio-coder/settings.yaml
OK   credentials            600
OK   state metadata         0.8.0 (repaired 2026-11-13T00:17:01.419Z)
OK   lifecycle migrations   9 registered, all recorded
OK   session store          /home/researcher/.local/state/clio-coder/sessions (no sessions recorded)
INFO telemetry              mode standard; research capture off; 0 workspace consents recorded
OK   installation files     build outputs present
OK   local worker capacity  24 usable CPUs, 19.4 GiB available memory; 8 local workers (built-in safety cap). GPU/VRAM and model fit are not checked.
OK   state storage          121 B (121 bytes); largest contributor home.json at 121 B (121 bytes)
OK   home storage           config 8.3 KB, data 0 B, cache 60.3 KB
OK   interop pi             version unknown (no ACP recipe) at /opt/node/bin/pi
INFO external tool asciinema not found (install with `clio-coder tools install asciinema`)
WARN external tool herdr    pane host 0.9.5 is not installed; run `clio-coder panes install`
OK   external tool yazi     experimental integration disabled by settings
INFO external tool croc     not found (install with `clio-coder tools install croc`)
INFO external tool cliamp   not found (install with `clio-coder tools install cliamp`)
OK   files pane profile     disabled by settings
OK   pdf attachments        /usr/bin/pdftotext: pdftotext version 24.02.0; pdfinfo /usr/bin/pdfinfo
OK   toolchain              found: cc, c++, gfortran, mpicc, mpicxx, mpirun, cmake, make, python3; not on PATH: clang, nvcc, ninja, meson, sbatch
INFO slurm mcp              not set up: clio-kit, sbatch, and squeue are not on PATH and no mcp.yaml declares the Slurm server; see docs/guide/slurm.md
OK   store backend          local (no selection; the default)
OK   store root             /home/researcher/.local/share/clio-coder/store (not created yet; 420.5 GiB free at /home/researcher/.local/share/clio-coder)
OK   panes mode             Clio's private pane host opens with bare `clio-coder`; this command is not running inside one
OK   panes layout           off
OK   naming                 clean: immutable history, git refs, worktree markers
OK   validation contract    none at the workspace root; rigor default normal
OK   shell sandbox          default-autonomy shell commands run in the bwrap sandbox; writable roots: /home/researcher, /tmp, /var/tmp, /home/researcher/.cache/clio-coder/sandbox-cache; 7 secret files in the workspace and scratch roots are masked; unix sockets: a seccomp filter refuses new AF_UNIX sockets (socketpair still works) and the kernel keyring calls; yolo runs contained in the same sandbox
17 rows folded; `clio-coder doctor --verbose` prints each one
~ $

  • Record readiness for this project

    Shell

    clio-coder fleet nodes test build-node --record
clio-coder fleet nodes list

    A passing recorded check makes the node ready for this project. A failed recorded check revokes previous eligibility. Records expire after one day and bind the entire connection configuration and client version. Changing the host, user, port, key or worker entry requires another recorded check.

    doctor --fix can record all node checks, along with its broader local repairs. Run plain doctor first to review those repairs. The node-specific test is the focused route when you only want to record one node.

  • Refresh after an upgrade or endpoint change

    Install the new exact client build when needed, then repeat the recorded test from the project root. A pinned task with an invalid or expired check fails with a reason; it does not silently run elsewhere.

    • Choose the first worker

    Keep the first task read-only and familiar. For example, ask CLIO Coder:

    Use a read-only Scout to inspect the README and explain this project's test command.
Before dispatching, ask me once where to run it, offering local and suitable verified fleet nodes.

    Scout is CLIO Coder's built-in read-only agent for finding your way around a codebase. When a verified node suits substantial work and no preference or pin exists, CLIO Coder asks once for the session. The choice remembers the exact node id for later unpinned work. The question does not replace the existing dispatch-plan approval. If you explicitly request build-node, it can be pinned directly.

    A Standing worker node preference, under Machines in the Workers area of /settings, persists across sessions. Placement priority is an explicit task node, a profile pin, the session choice, the standing preference, then local. Headless runs never ask; configure a preference or explicit pin before running them.

    Remote workers run under their own permits. The safety judge does not answer for a remote placement, so at default a remote worker's ordinary ask is denied. Worker slots limit concurrency; they do not create a scheduler allocation. On a university or laboratory cluster, use an approved execution environment. The Slurm guide describes separate allocation-aware tooling.

    Return edits from an independent checkout

    An editing dispatch to an independent node checkout must use worktree: true. Ask CLIO Coder to use an isolated task worktree, name the files the worker may change and declare the host checks you want before application.

    A matching branch and worktree are created on the node at the approved baseline. After the worker exits, CLIO Coder commits the worker's edits there, fetches the branch through the existing SSH connection and checks the returned baseline and permitted paths.

    The commit is imported into the owned local task worktree before the existing host verification and guarded apply flow. apply: "preserve" keeps the result on the local task branch, and clio-coder fleet land lists and lands such branches later.

    Transfer, verification and application failures preserve the node branch for recovery. The run record names the node, branch, worktree and returned commit when available. Inspect preserved work before merging or deleting it. A successful guarded merge permits remote cleanup. The node's original checkout stays at its old baseline, so update it deliberately before the next dispatch that needs the new commit.

    Follow the result

    Open Workers with Alt+W to see queued, active, failed and completed work with its actual node. In a session with panes, the same key opens a live dashboard beside the conversation. Review the worker result, receipt and project changes. The CLI's clio-coder fleet status and clio-coder fleet view <runId> expose durable results from another terminal.

    SSH nodes and delegated peers are separate execution paths. A delegated peer is not an SSH machine whose resources or project access CLIO Coder has verified.

    On a cluster

    Shell

    curl -fsSL https://coder.iowarp.ai/install.sh | sh

    The installer needs no root, refuses to run under sudo, and brings a private Node.js 24. On x64 login nodes with glibc from 2.17 to 2.27 it selects a compatible Node.js build. Behind a proxy, export https_proxy first; the cluster guide lists the variables for mirrored and offline installs.

    That private Node.js is not added to PATH. A node installed this way already has CLIO Coder, so skip fleet nodes install there and keep its version equal to your client's.

    CLIO Coder does not submit jobs for its own workers. The agent submits scheduler work through the clio-kit Slurm tools or the scheduler clients in bash, both under review; Submit a Slurm job walks through it.

    Boundaries

    By The CLIO Coder team · CLIO Coder

    Continue with the documentation