Connect another computer to a board

You have a Kanban board (set one up) and want a new computer to take part: to publish tasks, or to run a worker that claims them. This page initialises that computer from scratch on Linux, macOS, and Windows.

There are two ways a computer takes part, and they differ in what you must set up:

Before you start#

• The Loom CLI is installed on the new computer (Install the CLI) and loom --version prints a version. (A build without a release stamp prints loom version unknown: this build carries no release stamp; install a released build.)
• You can sign in as the same account that owns the board, or you hold the board's connection values (endpoint, store, server_key, store_key) from someone who does.
• A coding harness (Claude Code, Codex, or OpenCode) is installed and signed in for the OS user who will run it.
• git is on PATH. uv is installed by the Loom CLI at ~/.loom/bin/uv (Windows: %USERPROFILE%\.loom\bin\uv.exe); use that path or add it to PATH (from v0.672 the installer already does this for new terminals, and the scheduler finds uv there even when PATH lacks it). In this page, <runtime> means ~/.loom/cli (Windows: %USERPROFILE%\.loom\cli).

1. Bring the board's credentials onto this computer#

Choose one.

Sign in again (recommended)#

loom login

loom login repeats the sign-in: it asks for your email, then a one-time prompt to type I agree for the Privacy Policy and Terms of Service shown, then the emailed code at a hidden prompt. It provisions or re-reads your stores and merges them into ~/.loom/stores.toml. It does not touch any harness. It is the supported way to add a second computer.

Check you are on the same board. Login can bind kanban to a different, empty store than the one your first computer uses (for example a name ending in _kanban_2). When your account has two stores with the same name, loom login keeps the oldest, skips the other, and prints Warning: store <handle> was not configured locally: its section name [kanban] is already used by another of your stores and it needs a distinct alias. on stderr (the exit status stays 0). On both computers run:

grep -A3 '^\[kanban\]' ~/.loom/stores.toml

The store = values must be identical. If they differ, use the copy-by-hand section below to paste the first computer's [kanban] section instead.

Copy the section by hand#

If the account cannot sign in on this computer, an operator who already has the values can give you a [kanban] section to paste into ~/.loom/stores.toml (Windows: %USERPROFILE%\.loom\stores.toml):

default = "kanban"

[kanban]
endpoint         = "tcp://<server-host>:<port>"
store            = "<org>_kanban"
server_key       = "<server public key>"
store_key        = "<store key>"
namespace_scheme = "loom-8"
description      = "Team Kanban board"
web_origin       = "https://<your-host>"

A new stores.toml must have the top-level default line (before any section), or Loom refuses to read it. Always set web_origin on a private install: without it, web-service store commands (create_store, unlock_store, drop_store) are treated as hosted loomcloud.ai. When this is the only section in the file, loom setup also follows it. Reads (list_stores, load_store, query) work without it. namespace_scheme and description are optional in practice; still copy namespace_scheme exactly as it appears on the first computer.

2. Check that the computer can see the board#

loom list_stores

kanban (or your board's name) must appear. Then load it:

loom load_store --params '{"name":"kanban","set_default":false}'

Loading a store explicitly is what makes it available to an agent. A one-store file with default = "kanban" already has the board loaded, so you need load_store only to switch to it or when the file holds several stores.

3. Tell Loom which store is the board#

Add to ~/.loom/stores.toml if it is not already present:

[workspace]
loom-kanban = "kanban"

4. Initialise (idempotent)#

loom kanban_init --store kanban

Safe on a board that is already initialised. The first command on a new computer that embeds text (such as the first publish) downloads the embedding model, which needs access to huggingface.co, and prints download progress on stderr. Interactive sessions are now ready to publish ownerless tasks: see Daily use.

To prove the computer is on the right board, publish one ownerless task here as a script and read it back from the first computer. A script id script@<name> needs no harness session:

loom --store kanban kanban_publish_task --params '{"title":"join check","brief":"Delete me.","submitter_agent_id":"script@join-check","required_capabilities":{},"total_run_limit":1,"idempotency_key":"<unique>"}'
loom query --params '{"namespace":"kanban_user","rule_name":"kanban_list_tasks","args":["open"]}'

kanban_list_tasks is a query rule, so it is read with loom query, not as a tool. You should see the same task id on both computers.

(A codex@<id> id works from a plain shell only when Codex has a session file for that id on this computer; see step 5.)

5. Choose the agent identity#

An agent's identity is <harness>@<native-session-id>, for example codex@019f.... It comes from the harness's own conversation id, never from a process id, hostname, user name, or a random UUID. Read it with the whoami tool from inside the harness session:

loom whoami --params '{"harness":"codex"}'

Inside a harness session it reads the id from the harness environment (CODEX_THREAD_ID for Codex, CLAUDE_CODE_SESSION_ID for Claude Code) and prints agent_id, harness, native_conversation_id, os, and source (argument or the variable name it came from).

Outside a harness session this fails with loom: kanban identity: native conversation id unavailable for codex; agents run inside a harness (Claude or Codex) and pass its native id explicitly; a script may publish ownerless tasks as script@<name> (the message ended at pass the harness-native id explicitly before v0.674). Pass the id, or set the variable:

loom whoami --params '{"harness":"codex","native_conversation_id":"<id>"}'
CODEX_THREAD_ID=<id> loom whoami --params '{"harness":"codex"}'

For Claude Code, an invented CLAUDE_CODE_SESSION_ID in the environment fails with ... identifies no Claude Code session transcript, so it is a stale pre-resume id. An id passed as native_conversation_id in --params is not checked by whoami itself. From v0.674 a tool that needs the id to prove a live session (such as kanban_publish_task with an owner) also checks a Codex id used from a plain shell: it must name a real Codex session file on this computer, otherwise it fails with kanban identity: codex@<id> owns no Codex session file on this machine .... In earlier releases an arbitrary CODEX_THREAD_ID was accepted for the publish example above.

Any tool that takes an agent id (such as kanban_publish_task) needs the same id in the environment as the one you pass in its parameters, or it fails with the same error.

For a fixed-session worker the install step in section 6 creates and records the session for you.

6. Install a fixed-session worker#

Run this from an interactive, already-authenticated harness session on the computer you are enrolling, from inside the repository the worker should work in. It changes the operating system's schedule, so only do it on a computer and OS user you trust with unattended runs.

The simplest route is to ask the agent to use the installed worker workflow (the loom-kanban-worker skill):

Create one fixed-session Kanban worker for the board "kanban" in this repository, using the
operating system's native scheduler at its default cadence. Run the proof turn, verify
enrollment and the schedule, then heartbeat and scan. Do not claim a task yet.

The runner it drives, kanban_session_runner.py, has these commands. Run it through uv from <runtime> (~/.loom/cli; see Fleet for more). The examples below write uv for ~/.loom/bin/uv:

All of install, status, remove, and daemon also accept --store (default kanban) and --config.

Example, for an existing Codex session on Linux or macOS:

uv run --with pyzmq python <runtime>/kanban_session_runner.py preflight
uv run --with pyzmq python <runtime>/kanban_session_runner.py install \
  --harness codex --session-id <SESSION_ID> --repo /absolute/path/to/repo --store kanban
uv run --with pyzmq python <runtime>/kanban_session_runner.py status \
  --harness codex --session-id <SESSION_ID> --store kanban

uv run --with pyzmq python <runtime>\kanban_session_runner.py install `
  --harness codex --session-id <SESSION_ID> --repo C:\path\to\repo --store kanban

Do not use a "last session" shortcut or write your own shell loop; either can resume the wrong conversation and break ownership.

Harness credentials#

Where state lives, and what schedules it#

Warning (Windows): The task runs only while that user is signed in. After a reboot workers resume at the next sign-in; for unattended recovery configure Windows auto-login through normal OS administration. Loom does not store your OS password.

7. Confirm it worked#

1. Local: status for the worker (above) prints JSON. scheduler_installed must be true and agent must be non-null (the enrolled agent row). For a worker that was never installed it prints {"agent_id":"codex@<id>","scheduler_installed":false,"dormant":false,"agent":null}; agent: null means not enrolled.

2. Server: the agent appears in the board's agent list and its heartbeat is recent:

   loom query --params '{"namespace":"kanban_user","rule_name":"kanban_agent","args":[""]}'

   Look for <harness>@<session-id> with a fresh heartbeat. Heartbeats repeat about every 180 seconds; an idle worker that finds no work heartbeats and starts no model turn.

3. Hosted: the same worker shows on the Kanban page with state consistent idle and a recent heartbeat.

Not observed with a real enrolled worker: the agent row of status, and the consistent idle label in kanban_agent output and on the web page.

Remove a worker#

uv run --with pyzmq python <runtime>/kanban_session_runner.py remove \
  --harness codex --session-id <SESSION_ID> --store kanban

remove deletes the schedule, stops the process, retires the board identity, and deletes local state, including the worker's stored credential. A Claude worker will need a fresh token to be recreated.

Troubleshooting#