@netnodeag/kraftwerk 0.76.0 → 0.78.0

package/README.md

@@ -296,8 +296,8 @@ fields are optional. `workflows:` sets the workflows root, `output:` the
 run-artifact directory (default `output/`), `knowledge:` the OKF bundle root
 (default `knowledge/`), and `agents:` the agent-definition root (default
 `agents/`). `repos:` turns on the [repositories](#repositories) folder.
-`cloud:` tunes (or turns off) the registration with the
-[kraftwerk cloud](#inspector-in-the-kraftwerk-cloud), which is on by default.
+`cloud: { enabled: false }` leaves the workspace out of this machine's
+record in the [kraftwerk cloud](#this-machine-in-the-kraftwerk-cloud).
 
 `name:` is the title shown in the UI and can change freely. `slug:` is the
 workspace's address on this machine. It defaults to the folder name
@@ -486,38 +486,44 @@ repo. Agent logins made inside the container persist in the `agent-home`
 volume. This is a different image from the `kraftwerk-runner` sandbox
 (`runner/Dockerfile`) used by `run --sandbox`.
 
-### Inspector in the kraftwerk cloud
+### This machine in the kraftwerk cloud
 
 The kraftwerk cloud is the `~/.kraftwerk` registry made reachable over the
-internet: every `kraftwerk ui` registers there when it starts and sends a
-heartbeat while it runs, so you can see from anywhere which of your
-workspaces are up, on which machine, with which agents — and an admin sees
-every instance at once. **This is on by default.** The record carries the
-workspace name, icon and colour, the machine, the root, the version, and
-the agent and channel roster. Registration
-is best-effort: a cloud that is down never affects the UI.
-
-No key goes into kraftwerk.yml. The cloud hands the instance an identity
-(kept under `~/.kraftwerk/cloud/`, so a restart updates the record) and a
-**claim code**, shown under Settings → Cloud in the UI. Sign in at the
-cloud, type the code (or follow the "claim in the cloud" link), and the
-workspace appears under *My instances*; the instance learns about the claim
-with its next heartbeat.
+internet: the daemon (`kraftwerk daemon`) registers **this machine** once
+when it starts and sends a heartbeat while it runs; the workspaces it serves
+ride along as children of that record, so you can see from anywhere which
+of your workspaces are up, and where. **This is on by default.** A
+standalone `kraftwerk ui` never registers. Registration is best-effort: a
+cloud that is down never affects the UI.
+
+The machine's id is its relay id (the key in `~/.kraftwerk/relay.json`,
+created at the daemon's first start with the relay still off), proven with
+the relay secret. Until someone claims the machine it registers
+anonymously: workspace names, slugs and ids only, no paths. Claiming
+happens in the browser — no password passes through the CLI:
+
+```bash
+kraftwerk login --open    # prints (and opens) the claim link and code, waits for the claim
+kraftwerk cloud           # registered? claimed? url, machine id, last heartbeat
+kraftwerk logout          # release the machine; a fresh claim code follows
+kraftwerk cloud off       # turn it off for this machine (the daemon says goodbye); `on [--url]` back on
+```
+
+The claim code is also shown under Settings → Cloud. The switch and the
+cloud's origin live in `~/.kraftwerk/cloud.json` (`{ "enabled": false,
+"url": "…" }`); `KRAFTWERK_CLOUD_URL` in the environment wins (`off` turns
+the feature off — what the test suites set). In kraftwerk.yml, `cloud:` is
+a per-workspace veto only:
 
 ```yaml
 cloud:
-  url: https://srv.kraftwerk-cloud.netnode.cloud   # default
-  interval: 60                                     # seconds between heartbeats (default 60)
-  enabled: false                                   # opt out of the cloud for this workspace
+  enabled: false   # leave this workspace out of the machine's record
 ```
 
-`KRAFTWERK_CLOUD_URL` in the environment wins over the file (`off` turns the
-feature off everywhere — what the test suites set). A server that starts
-unattended and should register under an account without a claim puts an
-account token from the cloud UI into `.env` as `KRAFTWERK_CLOUD_TOKEN`; a
-`token:` key in kraftwerk.yml is refused. `/api/meta` reports the
-connection state and the claim code; `kraftwerk doctor` prints what the
-block will do.
+(`cloud.url` there is deprecated — honored with a warning when the machine
+names no origin — and `cloud.interval` is ignored: the cloud sets the
+cadence.) `/api/meta` and `/api/cloud` report the machine's state and claim
+code; `kraftwerk doctor` prints what happens to the workspace.
 
 ## Projects
 

package/dist/cli/cloud.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerCloudCommands(program: Command): void;

package/dist/cli/cloud.js

@@ -0,0 +1,262 @@
+import { spawn } from "node:child_process";
+import os from "node:os";
+import chalk from "chalk";
+import { CloudError, claimUrlFor, envCloudOff, machineCloud, machineGoodbye, machineHeartbeat, machineRegister, machineUnlink, writeCloudFile, } from "../core/cloud.js";
+import { findDaemon } from "../core/daemon.js";
+import { identityString, readIdentity } from "../core/identity.js";
+import { relayId, fromBase64Url } from "../client/relay.js";
+import { machineCredentials, readRelaySettings } from "../server/relay.js";
+import { getPkgVersion } from "../server/version.js";
+const POLL_MS = 2000;
+async function daemonCloud(port, method, route, body) {
+    const r = await fetch(`http://127.0.0.1:${port}${route}`, {
+        method,
+        headers: body ? { "content-type": "application/json" } : {},
+        ...(body ? { body: JSON.stringify(body) } : {}),
+        signal: AbortSignal.timeout(15_000),
+    });
+    const data = (await r.json().catch(() => ({})));
+    if (!r.ok)
+        throw new Error(data.error ?? `${r.status} from the daemon`);
+    return data;
+}
+const fail = (message, code = 1) => {
+    console.error(chalk.red(`✖ ${message}`));
+    process.exit(code);
+};
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch { }
+}
+/** The machine's id without creating a key: null before the daemon's first start (or `kraftwerk login`). */
+async function machineIdIfAny() {
+    const s = await readRelaySettings();
+    return s ? relayId(fromBase64Url(s.publicKey)) : null;
+}
+async function hello() {
+    const id = await readIdentity();
+    return { name: id.machine, handle: id.handle, hostname: os.hostname(), platform: `${process.platform}-${process.arch}`, version: await getPkgVersion() };
+}
+function printClaim(st) {
+    if (!st.claimCode)
+        return;
+    console.log(`  claim code  ${chalk.bold(st.claimCode)}`);
+    console.log(`  claim link  ${chalk.cyan(st.claimUrl ?? claimUrlFor(st.url, st.claimCode) ?? "")}`);
+}
+async function showStatus(opts) {
+    const [cloud, identity, id, daemon] = await Promise.all([machineCloud(), readIdentity(), machineIdIfAny(), findDaemon()]);
+    const live = daemon ? await daemonCloud(daemon.port, "GET", "/api/cloud").catch(() => null) : null;
+    const out = {
+        enabled: cloud.enabled,
+        url: cloud.url,
+        source: cloud.source,
+        ...(cloud.reason ? { reason: cloud.reason } : {}),
+        machine: identityString(identity),
+        id,
+        daemon: !!daemon,
+        state: live?.state ?? "off",
+        registered: live?.state === "connected",
+        claimed: !!live?.account,
+        account: live?.account ?? null,
+        claimCode: live?.claimCode ?? null,
+        claimUrl: live?.claimUrl ?? null,
+        lastSeen: live?.lastSeen ?? null,
+        interval: live?.interval ?? null,
+        workspaces: live?.workspaces ?? null,
+        ...(live?.error ? { error: live.error } : {}),
+    };
+    if (opts.json)
+        return void console.log(JSON.stringify(out, null, 2));
+    const dot = !cloud.enabled ? chalk.dim("○") : out.claimed ? chalk.green("●") : out.registered ? chalk.yellow("●") : chalk.dim("●");
+    console.log(`${dot} kraftwerk cloud ${cloud.enabled ? chalk.green("on") : chalk.dim("off")} ${chalk.dim(`${cloud.url} (${cloud.source})`)}`);
+    if (!cloud.enabled)
+        console.log(chalk.dim(`  ${cloud.reason}`));
+    console.log(`  machine     ${identityString(identity)} ${chalk.dim(id ?? "no id yet — created at the daemon's first start")}`);
+    if (!cloud.enabled)
+        return;
+    if (!daemon) {
+        console.log(`  state       ${chalk.dim("not reporting — the daemon registers this machine (`kraftwerk daemon start`)")}`);
+        return;
+    }
+    if (!live)
+        return void console.log(`  state       ${chalk.yellow("the daemon did not answer")}`);
+    if (live.state === "error")
+        console.log(`  state       ${chalk.red("error")} ${chalk.dim(live.error ?? "")}`);
+    else if (live.state !== "connected")
+        console.log(`  state       ${live.state}`);
+    else if (live.account)
+        console.log(`  state       ${chalk.green("claimed")} by ${chalk.bold(live.account)}`);
+    else
+        console.log(`  state       ${chalk.yellow("registered, unclaimed")} ${chalk.dim("— `kraftwerk login` claims it")}`);
+    if (live.state === "connected" && !live.account)
+        printClaim(live);
+    if (live.lastSeen)
+        console.log(`  heartbeat   ${new Date(live.lastSeen).toLocaleTimeString()} ${chalk.dim(`every ${live.interval ?? 60}s · ${live.workspaces ?? 0} workspace${live.workspaces === 1 ? "" : "s"} reported`)}`);
+}
+async function setEnabled(enabled, url) {
+    if (url && !/^https?:\/\/[^/?#]+\/?$/.test(url))
+        fail("--url is the cloud's origin, e.g. https://srv.kraftwerk-cloud.netnode.cloud", 2);
+    await writeCloudFile({ enabled, url });
+    const cloud = await machineCloud();
+    const daemon = await findDaemon();
+    // The daemon follows at once (off: goodbye); best-effort — the file is what counts at its next start.
+    const live = daemon ? await daemonCloud(daemon.port, "POST", "/api/cloud", { enabled, ...(url ? { url } : {}) }).catch(() => null) : null;
+    if (!enabled) {
+        console.log(`${chalk.green("✔")} cloud off for this machine ${chalk.dim(daemon ? (live ? "— the daemon said goodbye" : "— the daemon did not answer; it stops reporting at its next start") : "")}`);
+        return;
+    }
+    if (envCloudOff())
+        console.log(chalk.yellow("⚠ KRAFTWERK_CLOUD_URL=off in this environment keeps it off here"));
+    console.log(`${chalk.green("✔")} cloud on for this machine: ${chalk.cyan(cloud.url)}`);
+    if (!daemon)
+        console.log(chalk.dim("  the daemon registers this machine when it runs (`kraftwerk daemon start`); `kraftwerk login` claims it"));
+    else if (live?.state === "connected")
+        console.log(chalk.dim(live.account ? `  registered, claimed by ${live.account}` : "  registered — `kraftwerk login` claims it"));
+    else if (live?.state === "error")
+        console.log(chalk.yellow(`  the cloud did not answer: ${live.error ?? ""} (the daemon retries)`));
+}
+async function session() {
+    const daemon = await findDaemon();
+    if (daemon) {
+        const port = daemon.port;
+        // Off in the daemon (it read cloud.json before `login` turned it on): turning it on registers.
+        let first = true;
+        return {
+            status: async () => {
+                const st = first ? await daemonCloud(port, "POST", "/api/cloud", { enabled: true }) : await daemonCloud(port, "POST", "/api/cloud/sync");
+                first = false;
+                return st;
+            },
+            end: async () => { },
+        };
+    }
+    const cloud = await machineCloud();
+    const version = await getPkgVersion();
+    const creds = await machineCredentials();
+    let registered = false;
+    return {
+        status: async () => {
+            try {
+                const r = registered ? await machineHeartbeat(cloud.url, creds, { version }) : await machineRegister(cloud.url, creds, await hello(), []);
+                registered = true;
+                return { state: "connected", url: cloud.url, account: r.account, claimCode: r.claimCode, claimUrl: claimUrlFor(cloud.url, r.claimCode) };
+            }
+            catch (err) {
+                if (err instanceof CloudError && err.status === 403)
+                    throw new Error(`${cloud.url} refuses this machine's secret (403) — another machine holds this id`);
+                return { state: "error", url: cloud.url, error: err.message };
+            }
+        },
+        // Without a daemon nothing reports afterwards: the record says so now instead of after the grace period.
+        end: async () => {
+            if (registered)
+                await machineGoodbye(cloud.url, creds, version).catch(() => { });
+        },
+    };
+}
+async function login(opts) {
+    if (envCloudOff())
+        fail("KRAFTWERK_CLOUD_URL=off in this environment — unset it to log in", 2);
+    const timeout = Number(opts.timeout ?? 600);
+    if (!Number.isFinite(timeout) || timeout <= 0)
+        fail("--timeout must be a positive number of seconds", 2);
+    const before = await machineCloud();
+    if (!before.enabled) {
+        await writeCloudFile({ enabled: true });
+        console.log(chalk.dim("cloud turned on for this machine (`kraftwerk cloud off` turns it off)"));
+    }
+    const s = await session().catch((err) => fail(err.message));
+    try {
+        let st = await s.status();
+        if (st.state === "off")
+            fail(`the daemon keeps the cloud off: ${st.reason ?? "off"}`);
+        if (st.state !== "connected")
+            fail(`could not reach ${st.url}: ${st.error ?? st.state}`);
+        if (st.account) {
+            console.log(`${chalk.green("✔")} already logged in as ${chalk.bold(st.account)} ${chalk.dim(`(${st.url}) — \`kraftwerk logout\` releases this machine`)}`);
+            return;
+        }
+        if (!st.claimCode)
+            fail(`${st.url} handed out no claim code`);
+        console.log(`Sign in (or sign up) in the browser and claim this machine:`);
+        printClaim(st);
+        if (opts.open && st.claimUrl)
+            openBrowser(st.claimUrl);
+        console.log(chalk.dim(`waiting for the claim … (Ctrl-C stops; the code stays valid)`));
+        const until = Date.now() + timeout * 1000;
+        while (Date.now() < until) {
+            await new Promise((r) => setTimeout(r, Math.min(POLL_MS, Math.max(0, until - Date.now()))));
+            st = await s.status().catch((err) => ({ ...st, state: "error", error: err.message }));
+            if (st.account) {
+                console.log(`${chalk.green("✔")} logged in as ${chalk.bold(st.account)} ${chalk.dim(`— this machine is in your account at ${st.url}`)}`);
+                return;
+            }
+        }
+        fail(`not claimed within ${timeout}s — the code stays valid; \`kraftwerk login\` waits again`);
+    }
+    finally {
+        await s.end();
+    }
+}
+async function logout() {
+    if (envCloudOff())
+        fail("KRAFTWERK_CLOUD_URL=off in this environment", 2);
+    const cloud = await machineCloud();
+    if (!cloud.enabled)
+        fail(`the cloud is off for this machine — ${cloud.reason}`, 2);
+    const daemon = await findDaemon();
+    let st;
+    if (daemon) {
+        st = await daemonCloud(daemon.port, "POST", "/api/cloud/unlink").catch((err) => fail(err.message));
+    }
+    else {
+        const creds = await machineCredentials();
+        const r = await machineUnlink(cloud.url, creds, await getPkgVersion()).catch((err) => fail(err instanceof CloudError && err.status === 404 ? `this machine is not registered at ${cloud.url}` : `${cloud.url}: ${err.message}`));
+        st = { url: cloud.url, claimCode: r.claimCode, claimUrl: claimUrlFor(cloud.url, r.claimCode) };
+    }
+    console.log(`${chalk.green("✔")} logged out — this machine is unclaimed at ${st.url}`);
+    printClaim(st);
+    console.log(chalk.dim("  `kraftwerk login` claims it again"));
+}
+export function registerCloudCommands(program) {
+    const cloud = program
+        .command("cloud")
+        .description("This machine in the kraftwerk cloud: status, on, off (`kraftwerk login` claims it)")
+        .option("--json", "Machine-readable output")
+        .addHelpText("after", `
+The daemon registers this machine once; its open workspaces ride along.
+  kraftwerk cloud                 registered? claimed? url, machine id, last heartbeat
+  kraftwerk cloud on [--url <u>]  turn it on (~/.kraftwerk/cloud.json); the daemon follows at once
+  kraftwerk cloud off             turn it off; the running daemon says goodbye
+  kraftwerk login [--open]        claim this machine into your account (in the browser)
+  kraftwerk logout                release it
+A workspace stays out with \`cloud: { enabled: false }\` in its kraftwerk.yml.`)
+        .action(async (opts) => showStatus(opts));
+    cloud
+        .command("status")
+        .description("Registered? claimed? url, machine id, last heartbeat")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => showStatus({ json: opts.json ?? cloud.opts().json }));
+    cloud
+        .command("on")
+        .description("Turn the cloud on for this machine (the running daemon registers at once)")
+        .option("--url <url>", "The cloud's origin (default: the kraftwerk cloud)")
+        .action(async (opts) => setEnabled(true, opts.url));
+    cloud
+        .command("off")
+        .description("Turn the cloud off for this machine (the running daemon says goodbye)")
+        .action(async () => setEnabled(false));
+    program
+        .command("login")
+        .description("Claim this machine into your kraftwerk cloud account: prints the claim link and code, waits for the claim")
+        .option("--open", "Open the claim link in the browser")
+        .option("--timeout <seconds>", "How long to wait for the claim", "600")
+        .action(async (opts) => login(opts));
+    program
+        .command("logout")
+        .description("Release this machine from its kraftwerk cloud account (a fresh claim code follows)")
+        .action(async () => logout());
+}

package/dist/cli/daemon.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import { DAEMON_PORT, daemonState, lastOpenRoots, setDaemonVersion, writeDaemonFile } from "../core/daemon.js";
 import { tildify } from "../core/instances.js";
 import { networkUrls } from "../server/bind.js";
+import { startMachineCloud } from "../server/cloud.js";
 import { startPushWatcher } from "../server/push.js";
 import { applyRelay, relayPush } from "../server/relay.js";
 import { startHub } from "../server/server.js";
@@ -51,6 +52,14 @@ export async function runDaemon(opts) {
         console.log(`  ${chalk.cyan(o.url)} ${chalk.dim(o.name)}${o.aliasPort ? chalk.dim(` · also :${o.aliasPort}`) : ""}`);
     if (!hub.list().length)
         console.log(chalk.dim("  no workspace open yet — `kraftwerk ui` in a workspace folder opens it here"));
+    // The machine in the kraftwerk cloud: registered once, the open workspaces as its children (`kraftwerk cloud`, `kraftwerk login`).
+    const cloud = await startMachineCloud({ version: await getPkgVersion(), workspaces: () => hub.list(), owner: hub });
+    if (cloud.state === "connected") {
+        console.log(`${chalk.green("✔")} Cloud: ${chalk.cyan(cloud.url)} ${chalk.dim(cloud.account ? `(claimed by ${cloud.account})` : `(unclaimed — \`kraftwerk login\` claims this machine)`)}`);
+    }
+    else if (cloud.state === "error") {
+        console.log(`${chalk.yellow("⚠")} Cloud: ${cloud.url} unreachable — ${cloud.error ?? "no answer"} ${chalk.dim("(retrying; nothing else depends on it)")}`);
+    }
     // The relay (`kraftwerk remote on`): devices reach this machine from anywhere, end to end encrypted.
     const relay = await applyRelay(hub.port, await getPkgVersion(), (line) => console.log(chalk.dim(line)));
     // What needs you, pushed to the phones that asked (through the relay, sealed per device).

package/dist/cli/doctor.js

@@ -2,7 +2,8 @@ import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { addWorkspaceId, cloudFor, ignoreEntryFor, isDir, reposRootFor, resolveWorkspace, workspaceSlug } from "../config.js";
+import { machineCloud } from "../core/cloud.js";
+import { addWorkspaceId, ignoreEntryFor, isDir, reposRootFor, resolveWorkspace, workspaceSlug } from "../config.js";
 import { discoverWorkflows } from "../discover.js";
 import { missingEnv } from "../yaml.js";
 import { applyDotenv, DOTENV_FILE } from "../dotenv.js";
@@ -177,15 +178,22 @@ export async function runDoctor(cwd, opts = {}) {
             report("warn", `${these.length} routine(s) name the retired identity ${old}`, `${names(these)} · \`kraftwerk doctor --fix\` moves them to ${me} and commits`);
         }
     }
-    // Cloud manager: registration is best-effort at runtime, so doctor only says what would happen.
-    const cloud = cloudFor(project);
-    if (cloud) {
-        report("ok", `cloud: ${cloud.url}`, cloud.token
-            ? `registers under your kraftwerk account (KRAFTWERK_CLOUD_TOKEN), heartbeat every ${cloud.interval}s`
-            : `on by default — the UI shows a claim code under Settings → Cloud; opt out with cloud.enabled: false`);
+    // The kraftwerk cloud: the daemon registers the machine; doctor only says what would happen to this workspace.
+    const ymlCloud = project.config.cloud;
+    const cloud = await machineCloud(ymlCloud?.url ? [ymlCloud.url] : []);
+    if (ymlCloud?.enabled === false) {
+        report("info", "cloud: this workspace is left out", "cloud.enabled: false in kraftwerk.yml — the machine's cloud record does not list it");
+    }
+    else if (!cloud.enabled) {
+        report("info", "cloud: off", cloud.reason ?? "");
     }
     else {
-        report("info", "cloud: off", process.env.KRAFTWERK_CLOUD_URL?.trim().toLowerCase() === "off" ? "KRAFTWERK_CLOUD_URL=off" : "cloud.enabled: false in kraftwerk.yml");
+        report("ok", `cloud: ${cloud.url}`, "the daemon registers this machine and lists this workspace; `kraftwerk login` claims it, `kraftwerk cloud off` opts out");
+    }
+    if (ymlCloud?.url) {
+        report("warn", "kraftwerk.yml cloud.url is deprecated", cloud.source === "kraftwerk.yml"
+            ? `the cloud is the machine's now — \`kraftwerk cloud on --url ${ymlCloud.url}\`, then remove it from kraftwerk.yml`
+            : `ignored: the machine's cloud is ${cloud.url} (${cloud.source}) — remove it from kraftwerk.yml`);
     }
     const found = project.workflowsRoot ? await discoverWorkflows(cwd) : [];
     if (!project.workflowsRoot) {

package/dist/cli/init.js

@@ -31,8 +31,8 @@ skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packag
 #   root: ${DATA_DIR}/repos       # clones land here (git-ignored); a bare \`repos:\` uses repos/ instead
 # vibeables:                      # small apps built live in a chat with a preview pane (uncomment to enable; one folder per app under ${DATA_DIR}/vibeables, versioned with the workspace)
 # projects:                       # goal-scoped folders — brief, systems of record, links to knowledge/vibeables/repos/workflows/agents — that chats work in (uncomment to enable; one folder per project under ${DATA_DIR}/projects)
-# cloud:                          # the kraftwerk cloud is ON BY DEFAULT: \`kraftwerk ui\` registers this workspace there and shows a claim code under Settings → Cloud
-#   enabled: false                # uncomment both lines to keep this workspace out of the cloud (or set KRAFTWERK_CLOUD_URL=off for the whole machine)
+# cloud:                          # the daemon registers this MACHINE with the kraftwerk cloud and lists this workspace (\`kraftwerk login\` claims the machine)
+#   enabled: false                # uncomment both lines to leave this workspace out (\`kraftwerk cloud off\` turns the cloud off for the whole machine)
 `;
 const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
 name: hello

package/dist/cli/invite.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerInviteCommand(program: Command): void;

package/dist/cli/invite.js

@@ -0,0 +1,48 @@
+import chalk from "chalk";
+import { resolveWorkspace, workspaceSlug } from "../config.js";
+import { findDaemon } from "../core/daemon.js";
+const fail = (message, code = 1) => {
+    console.error(chalk.red(`✖ ${message}`));
+    process.exit(code);
+};
+export function registerInviteCommand(program) {
+    program
+        .command("invite")
+        .description("Invite someone into this workspace as a remote member (no clone): prints the join code and link — the machine must be claimed (`kraftwerk login`)")
+        .option("--role <role>", "member (default) or owner")
+        .option("--workspace <slug>", "A workspace the daemon serves, instead of the one in this folder")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        if (opts.role !== undefined && opts.role !== "owner" && opts.role !== "member")
+            fail("--role is member or owner", 2);
+        let which;
+        if (opts.workspace)
+            which = { slug: opts.workspace };
+        else {
+            const ws = await resolveWorkspace(process.cwd()).catch((err) => fail(err.message));
+            if (!ws.configPath)
+                fail("not in a workspace folder (no kraftwerk.yml here or above) — run it there, or pass --workspace <slug>", 2);
+            if (!ws.config.id)
+                fail("this workspace has no id (ws_…) in kraftwerk.yml — run `kraftwerk doctor --fix`");
+            which = { root: ws.root, slug: workspaceSlug(ws) };
+        }
+        const daemon = await findDaemon();
+        if (!daemon)
+            fail("the daemon is not running — `kraftwerk daemon start` (it holds this machine's place in the cloud)");
+        const r = await fetch(`http://127.0.0.1:${daemon.port}/api/cloud/invite`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ ...which, ...(opts.role ? { role: opts.role } : {}) }),
+            signal: AbortSignal.timeout(20_000),
+        }).catch((err) => fail(`the daemon did not answer: ${err.message}`));
+        const data = (await r.json().catch(() => ({})));
+        if (!r.ok)
+            fail(data.error ?? `${r.status} from the daemon`);
+        if (opts.json)
+            return void console.log(JSON.stringify(data, null, 2));
+        console.log(`${chalk.green("✔")} invite to ${chalk.bold(data.workspace.name)} ${chalk.dim(`(${data.workspace.slug}, ${data.workspace.id})`)} as ${data.role}`);
+        console.log(`  code        ${chalk.bold(data.code)}`);
+        console.log(`  join link   ${chalk.cyan(data.url)}`);
+        console.log(chalk.dim(`  valid until ${new Date(data.expiresAt).toLocaleString()} — they join in the cloud and reach the workspace through this machine`));
+    });
+}

package/dist/cli/kraftwerk.js

@@ -22,6 +22,8 @@ import { registerDaemonCommand } from "./daemon.js";
 import { registerRemoteCommand } from "./remote.js";
 import { registerJournalCommands } from "./journal.js";
 import { registerWhoamiCommand } from "./whoami.js";
+import { registerCloudCommands } from "./cloud.js";
+import { registerInviteCommand } from "./invite.js";
 import { applyDotenv } from "../dotenv.js";
 import { resolveWorkspace } from "../config.js";
 import { registerRoutineCommands } from "./routines.js";
@@ -46,6 +48,9 @@ import { runUi } from "./ui.js";
  *   kraftwerk trash ...               what was deleted: list, restore, purge, empty
  *   kraftwerk devices ...             paired devices: list, pair one, revoke one
  *   kraftwerk daemon                  the machine's kraftwerk: every open workspace at <slug>.localhost
+ *   kraftwerk cloud [on|off|status]   this machine in the kraftwerk cloud (the daemon registers it)
+ *   kraftwerk login / logout          claim this machine into your cloud account (in the browser) / release it
+ *   kraftwerk invite [--role owner]   invite a remote member into this workspace (join code + link, via the daemon)
  *   kraftwerk doctor [--fix]          preflight: harness CLIs, docker, workflows, env, routine runners
  *   kraftwerk validate [paths...]     validate without executing
  *
@@ -302,6 +307,8 @@ registerDaemonCommand(program);
 registerRemoteCommand(program);
 registerJournalCommands(program);
 registerWhoamiCommand(program);
+registerCloudCommands(program);
+registerInviteCommand(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/client/relay.d.ts

@@ -28,6 +28,12 @@
  * presents a paired device's token like any network caller, and the daemon
  * applies the same trust rules (src/server/trust.ts). Anyone holding the
  * pairing link still needs a pairing code or a token.
+ *
+ * Or, as a remote member of one workspace, it sends `{t:"auth",
+ * memberToken, workspaceId}` as its first sealed message and waits for the
+ * daemon's `{t:"auth", ok, …}` (src/server/members.ts): the whole channel
+ * is then that member's, scoped to that workspace. A client that sends no
+ * auth is a device's channel exactly as before.
  */
 export declare const RELAY_PROTOCOL = 1;
 export declare function toBase64(bytes: Uint8Array): string;
@@ -96,7 +102,27 @@ export type TunnelToDaemon = {
 } | {
     t: "abort";
     id: number;
+}
+/** A member session: first, once, before any request (see src/server/members.ts). */
+ | {
+    t: "auth";
+    memberToken: string;
+    workspaceId: string;
 };
+/** Who the cloud says the member is, and the workspace the session is scoped to. */
+export interface MemberAuth {
+    member: {
+        email: string;
+        handle: string;
+        role: "owner" | "member";
+    };
+    /** `slug` addresses it: /w/<slug>/api/… */
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+}
 export type TunnelToClient = {
     t: "res";
     id: number;
@@ -113,6 +139,13 @@ export type TunnelToClient = {
     t: "fail";
     id: number;
     error: string;
+} | ({
+    t: "auth";
+    ok: true;
+} & MemberAuth) | {
+    t: "auth";
+    ok: false;
+    error: string;
 };
 /** The socket the client talks over — the browser's WebSocket and Node's global one both fit. */
 export interface RelaySocket {
@@ -134,6 +167,8 @@ export interface Tunnel {
     close(): void;
     /** Resolves when the connection ends, with why. */
     readonly closed: Promise<string>;
+    /** A member session's answer (ConnectOptions.member); absent on a device's channel. */
+    readonly member?: MemberAuth;
 }
 export interface ConnectOptions {
     /** The relay's client endpoint, e.g. wss://srv.kraftwerk-cloud.netnode.cloud/api/relay/client */
@@ -144,6 +179,11 @@ export interface ConnectOptions {
     connect?: (url: string) => RelaySocket;
     /** Abort the handshake after this long (default 15 s). */
     timeoutMs?: number;
+    /** Open the channel as a remote member of one workspace instead of a device: the daemon verifies it with the cloud. */
+    member?: {
+        token: string;
+        workspaceId: string;
+    };
 }
 /** Connect to a machine through the relay: the handshake, then a `fetch` that goes through it. */
 export declare function connectTunnel(opts: ConnectOptions): Promise<Tunnel>;

package/dist/client/relay.js

@@ -28,6 +28,12 @@
  * presents a paired device's token like any network caller, and the daemon
  * applies the same trust rules (src/server/trust.ts). Anyone holding the
  * pairing link still needs a pairing code or a token.
+ *
+ * Or, as a remote member of one workspace, it sends `{t:"auth",
+ * memberToken, workspaceId}` as its first sealed message and waits for the
+ * daemon's `{t:"auth", ok, …}` (src/server/members.ts): the whole channel
+ * is then that member's, scoped to that workspace. A client that sends no
+ * auth is a device's channel exactly as before.
  */
 const subtle = () => globalThis.crypto.subtle;
 const enc = new TextEncoder();
@@ -167,6 +173,7 @@ export async function connectTunnel(opts) {
     const closed = new Promise((r) => (resolveClosed = r));
     const pending = new Map();
     let nextId = 1;
+    let onAuth = null;
     const finish = (why) => {
         if (closedWhy)
             return;
@@ -230,6 +237,11 @@ export async function connectTunnel(opts) {
         });
     });
     const receive = (msg) => {
+        if (msg.t === "auth") {
+            onAuth?.(msg);
+            onAuth = null;
+            return;
+        }
         const p = pending.get(msg.id);
         if (!p)
             return;
@@ -277,6 +289,28 @@ export async function connectTunnel(opts) {
         ws.send(await channel.seal(JSON.stringify(msg)));
     };
     await ready;
+    let member;
+    if (opts.member) {
+        const m = opts.member;
+        const answer = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("the machine did not answer the member's hello")), opts.timeoutMs ?? 15_000);
+            onAuth = (msg) => {
+                clearTimeout(timer);
+                resolve(msg);
+            };
+            void closed.then((why) => {
+                clearTimeout(timer);
+                reject(new Error(why));
+            });
+            send({ t: "auth", memberToken: m.token, workspaceId: m.workspaceId }).catch(reject);
+        });
+        if (!answer.ok) {
+            ws.close(1000, "bye");
+            finish(answer.error);
+            throw new Error(answer.error);
+        }
+        member = { member: answer.member, workspace: answer.workspace };
+    }
     const tunnelFetch = async (input, init) => {
         if (closedWhy)
             throw new Error(closedWhy);
@@ -314,5 +348,6 @@ export async function connectTunnel(opts) {
             finish("closed");
         },
         closed,
+        ...(member ? { member } : {}),
     };
 }