@netnodeag/kraftwerk 0.64.0 → 0.66.0

package/README.md

@@ -7,16 +7,18 @@ happened to set them up, and every result is checked before anyone relies on
 it.
 
 ```bash
-npm install -g @netnodeag/kraftwerk
+npm install -g @netnodeag/kraftwerk    # once per machine
 
-cd your-project
-kraftwerk init                         # scaffold the workspace
-kraftwerk doctor                       # check harnesses, docker, workflows, env vars, legacy leftovers
-kraftwerk ui                           # open it at http://localhost:1981
+cd your-project                        # any folder: a repo, a team folder, an empty one
+kraftwerk init                         # make it a workspace: kraftwerk.yml + kraftwerk-data/
+kraftwerk doctor                       # check that the agents (Claude Code, Codex, Pi) are there
+kraftwerk ui                           # start it, then open http://localhost:1981
 ```
 
 Needs Node 20+ and at least one agent harness (Claude Code, Codex, or Pi).
-Details in [Install](#install).
+[Start and use kraftwerk](#start-and-use-kraftwerk) explains the ways to
+run it (one workspace, several at once, from your phone);
+[Install](#install) has the details.
 
 **Why teams need it.** AI work today lives in individual silos. Personal
 prompts, Claude Code sessions, one-off scripts. What one person figures out
@@ -48,6 +50,68 @@ becomes shared practice.
 This README is the reference for the framework and CLI. For the overview,
 start at the [project README](https://github.com/NETNODEAG/kraftwerk#readme).
 
+## Start and use kraftwerk
+
+A **workspace** is a folder with a `kraftwerk.yml`: its agents, knowledge,
+workflows, projects and chats live in it (under `kraftwerk-data/`), and git
+can share it with your team. `kraftwerk init` makes any folder one.
+kraftwerk is then used in the browser, the **inspector**, which a kraftwerk
+process serves from your machine. There are three ways to run that process.
+
+**One workspace: `kraftwerk ui`.** In the workspace folder, `kraftwerk ui`
+starts a server for it and prints the address, `http://localhost:1981`
+(`port:` in kraftwerk.yml, or `--port`, sets another). It runs in the
+foreground; Ctrl-C stops it. That is all most people need.
+
+**Several workspaces: `kraftwerk daemon`.** With more than one workspace,
+run one kraftwerk for all of them instead of a server and a port each.
+Start the daemon once and leave it running (a terminal tab, or a login
+item):
+
+```bash
+kraftwerk daemon                       # the machine's kraftwerk, on http://localhost:1980
+
+cd ~/work/team-blau && kraftwerk ui    # opens this workspace in the daemon:
+                                       #   http://team-blau.localhost:1980
+cd ~/work/relaunch && kraftwerk ui     #   http://relaunch.localhost:1980
+kraftwerk workspaces                   # every workspace on this machine, running or not
+kraftwerk workspaces stop team-blau    # close one; the daemon and the others keep running
+```
+
+Each workspace is addressed by its **slug**: the folder name, or `slug:` in
+kraftwerk.yml (the `name:` is only the title and can change freely).
+Browsers resolve `<slug>.localhost` to your machine by themselves, so there
+is nothing to set up, and each workspace keeps its own browser origin.
+Where a host name per workspace is not possible, `http://localhost:1980/w/<slug>/`
+reaches the same workspace. `http://localhost:1980` lists what is open.
+A workspace with a `port:` of its own is served there too, so old links
+keep working. The daemon remembers what was open and opens it again when it
+starts (after a reboot or an update). Each workspace still runs on its own
+inside it, with its own `.env`, routines, git sync and chats.
+`kraftwerk ui` hands the workspace to the daemon whenever one is running;
+`kraftwerk ui --standalone` starts a server of its own anyway.
+
+**From your phone or another computer.** Add `--lan` (`kraftwerk ui --lan`,
+or `kraftwerk daemon --lan`) and kraftwerk also listens on your network.
+Anyone who opens it there gets a pairing screen, nothing else, until you
+pair that device: `kraftwerk devices pair` on this machine prints a
+one-time code (see [Inspector on your phone](#inspector-on-your-phone-paired-devices)).
+
+**What to do first in the inspector.** Talk to **Ralv**, the workspace's
+general chat, in plain words: it knows what is in the workspace and helps
+set up the rest. From there:
+
+- **Agents** are persistent coworkers with a role, a memory and routines.
+  Open one and chat with it; its sessions continue where they ended.
+- **Projects** gather a goal, a brief and links; every chat in a project
+  starts with that context.
+- **Workflows** are repeatable processes with checked results; run one from
+  its page or with `kraftwerk run <workflow> "<request>"`.
+- **Knowledge** is the shared, human-verified context agents read.
+
+Everything you see in the inspector is files in the workspace folder, so
+the CLI (`kraftwerk --help`) and git work on the same things.
+
 ## Under the hood
 
 Deterministic workflow-as-code over headless agent harnesses, in the spirit of
@@ -112,7 +176,7 @@ cd your-project
 kraftwerk init                     # scaffold kraftwerk.yml + kraftwerk-data/ (workflow, agent, knowledge)
 kraftwerk doctor                   # preflight: harness CLIs, docker, workflows, declared env vars, legacy leftovers
 kraftwerk run hello "Was ist kraftwerk?"
-kraftwerk ui                       # inspector on http://localhost:1981
+kraftwerk ui                       # inspector on http://localhost:1981 (see Start and use kraftwerk)
 ```
 
 The same without a global install:
@@ -159,8 +223,10 @@ kraftwerk run tagline "https://..."     # run; --yes, --verbose
 kraftwerk run                           # interactive: pick workflow, type the request
 kraftwerk runs                          # past runs from output/*/trace.jsonl; runs show <id> for detail
 kraftwerk knowledge                     # Knowledge: OKF bundles (list/get/put/verify/search/...)
-kraftwerk ui                            # inspector web UI on http://localhost:1981; --port, --output
+kraftwerk ui                            # start this workspace: http://localhost:1981 (or open it in the daemon); --port, --lan, --standalone
+kraftwerk daemon                        # one kraftwerk for every open workspace: http://<slug>.localhost:1980; --port, --lan
 kraftwerk workspaces                    # every workspace on this machine; workspaces start|stop|forget <ref>
+kraftwerk devices                       # paired devices (a phone, another computer); devices pair|revoke
 kraftwerk projects                      # goal-scoped project folders; projects create|show|link|log|remove
 kraftwerk trash                         # what was deleted; trash restore|purge <id>, trash empty
 kraftwerk journal <agent> ["<entry>"]   # an agent's memory across sessions: print it, add a line (--kind)
@@ -171,8 +237,6 @@ kraftwerk create "was der Workflow tun soll"   # for LLM agents: prints a build
 kraftwerk runner build                  # build the Docker sandbox image (once)
 kraftwerk run --sandbox website-check "https://..."   # isolated container per run; --ssh forwards the agent
 kraftwerk runner ps / stop <run-id>     # see / stop running sandbox containers
-kraftwerk tunnel setup kw.example.com   # Cloudflare Tunnel to the inspector: login, create, route dns, kraftwerk.yml
-kraftwerk tunnel                        # run that tunnel alone (the UI runs elsewhere)
 ```
 
 Nothing is deleted at once. Removing an agent, a project, a workflow, a knowledge
@@ -184,20 +248,18 @@ The **trash** screen (`#/trash`) or `kraftwerk trash restore <id>` puts an entry
 back where it came from. Deleting it there, or `kraftwerk trash empty`, makes it
 final. A chat's agent transcripts are only removed then, so a restored chat can resume.
 
-The inspector binds `127.0.0.1` — it has no authentication of its own and
-its chat runs coding agents against the repo, so it stays off the LAN, and
-while bound there it only answers requests whose `Host` is a loopback name
-(so a page on another site cannot reach it by re-pointing its own DNS at
-127.0.0.1). Inside a container it binds all interfaces instead, because the
-port mapping is the boundary there (`deploy-starter/` publishes to
-localhost, and its traefik override adds basic-auth). `KRAFTWERK_UI_HOST`
-overrides the default either way. A reverse proxy in front of it must set
-`X-Forwarded-Host` to the host the browser addressed (Caddy and traefik do
-by default; nginx needs `proxy_set_header X-Forwarded-Host $host;`): the
-loopback bind answers a non-loopback `Host` only when that header is
-present or the name is the project's `public:` hostname, and state-changing
-requests are refused when `Origin` names a different host. See
-[Inspector through a Cloudflare Tunnel](#inspector-through-a-cloudflare-tunnel).
+The inspector binds `127.0.0.1`: its chat runs coding agents against the
+repo, so it stays off the network unless you ask (`--lan`), and there only
+paired devices get in. While bound to loopback it only answers requests
+whose `Host` is a loopback name or `<slug>.localhost` (so a page on another
+site cannot reach it by re-pointing its own DNS at 127.0.0.1). Inside a
+container it binds all interfaces instead, because the port mapping is the
+boundary there (`deploy-starter/` publishes to localhost, and its traefik
+override adds basic-auth). `KRAFTWERK_UI_HOST` overrides the default either
+way. A reverse proxy in front of it must set `X-Forwarded-Host` to the host
+the browser addressed (Caddy and traefik do by default; nginx needs
+`proxy_set_header X-Forwarded-Host $host;`), and its visitors pair like any
+other device.
 
 ### The kraftwerk.yml project config
 
@@ -206,16 +268,19 @@ 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.
-`public:` and `tunnel:` expose the inspector through a
-[Cloudflare Tunnel](#inspector-through-a-cloudflare-tunnel). `cloud:`
-tunes (or turns off) the registration with the
+`cloud:` tunes (or turns off) the registration with the
 [kraftwerk cloud](#inspector-in-the-kraftwerk-cloud), which is on by default.
 
+`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
+(`~/Sites/team-blau` becomes `team-blau`). It must be lowercase letters,
+digits and dashes, and unique among the workspaces on the machine.
+`kraftwerk ui` and `kraftwerk doctor` warn when two workspaces share one.
+
 A `.env` next to kraftwerk.yml (`KEY=value` lines, `#` comments, quotes)
 is loaded into every kraftwerk process at start: `kraftwerk ui` and the
 server it supervises, so a restart from the UI re-reads the file; the chat
-agents, routines and workflow runs the inspector spawns; the tunnel
-(`TUNNEL_TOKEN`); `requires:` checks in `run` and `doctor`. A variable the
+agents, routines and workflow runs the inspector spawns; `requires:` checks in `run` and `doctor`. A variable the
 shell already sets wins over the file. A project started from another
 workspace's inspector gets its own `.env`, not the other one's. The file is
 never synced (it is on the workspace git's deny list and in the .gitignore
@@ -304,6 +369,33 @@ agent such as Claude Code or Codex. It prints a self-contained brief covering
 the schema example, gates, harness rules and verify ladder, which the agent
 follows to author the workflow folder and validate and smoke it with this CLI.
 
+### Inspector on your phone (paired devices)
+
+`kraftwerk ui --lan` also listens on your network and prints the addresses
+(for example `http://192.168.1.20:1981`). Anyone who opens one gets a
+pairing screen, nothing else. To let a device in, make a one-time code on
+the machine kraftwerk runs on, with `kraftwerk devices pair` or settings →
+devices → pair a device, and enter it on the device. The code works once,
+for 10 minutes. The device stays paired until you unpair it in the same
+place (`kraftwerk devices revoke <id>`), and its access ends at once.
+
+One pairing covers every workspace on the machine. The tokens live in
+`~/.kraftwerk/devices.json` as hashes only. A browser keeps its token as
+an HttpOnly cookie. An app sends it as `Authorization: Bearer`, or as
+`?token=` on the socket. A paired device can use everything except
+managing devices, which stays on the machine itself. Requests from the
+machine itself need no pairing.
+Inside a container nothing changes: the port mapping is the boundary.
+`KRAFTWERK_UI_TRUST_NETWORK=1` brings back the old behaviour of trusting
+every network caller, and `kraftwerk doctor` warns while it is set.
+Behind a reverse proxy on the same machine, the proxy must send
+`X-Forwarded-For` (or `X-Forwarded-Host`), so its visitors pair like any
+other device. If it cannot, set `KRAFTWERK_UI_REQUIRE_PAIRING=1`, which
+makes every request pair, this machine's own included.
+
+For a client of your own, `@netnodeag/kraftwerk/client` takes the token:
+`createClient({ baseUrl, token })`.
+
 ### Inspector on a server
 
 The repo root ships [`deploy-starter/`](../deploy-starter/). Copy it into your
@@ -311,117 +403,13 @@ consumer repo as `deploy/` and it builds a small image, this package from npm
 plus the claude, codex and pi CLIs, that serves `kraftwerk ui` for that repo
 bind-mounted at `/work`. `compose.yml` is localhost-only, reachable over an
 SSH tunnel. `compose.traefik.yml` layers traefik routing and mandatory
-basic-auth on top. Treat that auth as load-bearing. The UI has no
-authentication of its own and its chat runs coding agents against the mounted
+basic-auth on top. Treat that auth as load-bearing. In a container the UI
+trusts whoever reaches it (the port mapping is the boundary, so device
+pairing does not apply), and its chat runs coding agents against the mounted
 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 through a Cloudflare Tunnel
-
-The other way to reach a laptop's or server's inspector from elsewhere: no
-open port, no reverse proxy, no certificate. `kraftwerk ui` runs
-[cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
-next to the inspector and the loopback bind becomes reachable at a hostname
-on a domain you have on Cloudflare.
-
-You need a Cloudflare account with a domain added to it (the free plan is
-enough), and cloudflared on the machine:
-
-```bash
-brew install cloudflared          # macOS; Linux packages: developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
-```
-
-**1. Create the tunnel and route a hostname to it.** From the project root:
-
-```bash
-kraftwerk tunnel setup kw.example.com
-```
-
-This opens the browser for `cloudflared tunnel login` when there is no
-certificate yet (pick the zone `kw.example.com` belongs to), creates a
-tunnel named `kraftwerk-<project name>` (or `--name`), adds the CNAME from
-the hostname to it, and writes the result into kraftwerk.yml:
-
-```yaml
-public: https://kw.example.com   # the hostname the tunnel routes to
-tunnel:
-  name: kraftwerk-agent-playground
-```
-
-A second run reuses the login and the tunnel. If the hostname already has a
-DNS record, setup says so and `--overwrite-dns` replaces it. If cloudflared
-quietly routed `kw.example.com.other-zone.com` instead, because the hostname
-is outside the zone you logged in to, setup refuses and names the stray
-record to delete before you log in to the right zone and run it again.
-
-**2. Put a Cloudflare Access policy on the hostname.** The UI has no login
-of its own and its chat runs coding agents against the workspace, so the
-tunnel must never be the only thing between the internet and it. In the
-[Zero Trust dashboard](https://one.dash.cloudflare.com/) go to Access →
-Applications → Add an application → Self-hosted, enter `kw.example.com` as
-the domain, and add a policy: emails ending in your domain with a one-time
-PIN, a Google or GitHub login, whatever fits. Access is free for up to 50
-users. From then on Cloudflare shows a login page before anything reaches
-the tunnel.
-
-**3. Let the inspector verify that login.** On the application's overview
-page copy the Application Audience (AUD) tag, and take your team name from
-the team domain `https://<team>.cloudflareaccess.com`:
-
-```yaml
-tunnel:
-  name: kraftwerk-agent-playground
-  access:
-    team: my-team
-    aud: 4714c1358e65fe4b408ad6d432a5f878f08194bdb4752441fd56faefa9b2b6f2
-```
-
-With this block the inspector checks the `Cf-Access-Jwt-Assertion` token
-Access adds to every request, against the team's public keys, the audience
-tag and the clock. A removed or misconfigured policy then fails closed with
-a 401 instead of exposing the UI. Skipping the block works, and
-`kraftwerk doctor` warns about it every time.
-
-**4. Start.** `kraftwerk ui` now starts cloudflared with the inspector,
-keeps it across UI restarts and stops it with the UI:
-
-```
-✔ Kraftwerk UI: http://localhost:1981
-✔ Public URL: https://kw.example.com
-↗ tunnel: running kraftwerk-agent-playground → https://kw.example.com → http://127.0.0.1:1981
-  cloudflared │ ... Registered tunnel connection ...
-```
-
-Open `https://kw.example.com` from anywhere, log in through Access, and you
-are in the same inspector. `localhost:1981` on the machine itself keeps
-working without a login. `kraftwerk doctor` reports the tunnel, the Access
-block and whether cloudflared is installed.
-
-**Variants.** `kraftwerk tunnel` runs the configured tunnel alone, for an
-inspector that already runs elsewhere (started by `kraftwerk workspaces
-start`, or in a container). For a tunnel created in the Zero Trust
-dashboard instead (Networks → Tunnels), leave `name` out, route the
-hostname to `http://localhost:<port>` there and export its token as
-`TUNNEL_TOKEN` before `kraftwerk ui`. `public:` on its own, without
-`tunnel:`, is for any other proxy that forwards the browser's `Host`
-without setting `X-Forwarded-Host`.
-
-**Troubleshooting.** cloudflared's lines appear prefixed with
-`cloudflared │`. "Cannot determine default origin certificate path" means no
-login on this machine: run `cloudflared tunnel login` or setup again. "tunnel
-not found" means the name in kraftwerk.yml does not exist in the account
-that logged in; `cloudflared tunnel list` shows what does. A tunnel that
-dies three times right after launch is given up and the UI stays local
-until the next start. A 421 "unexpected Host header" in the browser means
-`public:` does not match the hostname you opened. A 401 means Access is
-configured in kraftwerk.yml but the token is missing or wrong: the
-hostname has no Access application, or `team`/`aud` do not match it.
-
-Quick tunnels (`trycloudflare.com`) are deliberately not supported: Access
-cannot be attached to them, which would leave the UI open to anyone with
-the URL.
-
 ### Inspector in the kraftwerk cloud
 
 The kraftwerk cloud is the `~/.kraftwerk` registry made reachable over the
@@ -429,8 +417,8 @@ 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, the
-public URL if there is one, and the agent and channel roster. Registration
+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

package/dist/acp.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
 import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+import { workspaceEnv } from "./core/env.js";
 const ADAPTERS = {
     claude: "@agentclientprotocol/claude-agent-acp/dist/index.js",
     codex: "@agentclientprotocol/codex-acp/dist/index.js",
@@ -21,7 +22,8 @@ const CLAUDE_THINKING_BUDGET = {
  * the session config it hands to `codex app-server`.
  */
 export function adapterEnv(agent, tuning) {
-    const env = { ...process.env };
+    // The workspace's environment when a server runs this (one per workspace, see core/env.ts); a CLI run has none and gets process.env.
+    const env = workspaceEnv();
     if (agent === "claude" && tuning.effort && CLAUDE_THINKING_BUDGET[tuning.effort]) {
         env.MAX_THINKING_TOKENS = String(CLAUDE_THINKING_BUDGET[tuning.effort]);
     }

package/dist/cli/daemon.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+/**
+ * `kraftwerk daemon` — the machine's kraftwerk: one process serving every
+ * open workspace, each at `<slug>.localhost:<port>` (and its own port, when
+ * free). `kraftwerk ui` in a workspace folder opens it there; `kraftwerk
+ * workspaces stop <root>` closes it; the daemon reopens what was open when it
+ * starts again. Runs in the foreground, restarted by a supervisor after a
+ * self-update like `kraftwerk ui`.
+ */
+export declare function runDaemon(opts: {
+    port?: string;
+    lan?: boolean;
+}): Promise<void>;
+export declare function registerDaemonCommand(program: Command): void;

package/dist/cli/daemon.js

@@ -0,0 +1,60 @@
+import chalk from "chalk";
+import { DAEMON_PORT, findDaemon, lastOpenRoots, writeDaemonFile } from "../core/daemon.js";
+import { tildify } from "../core/instances.js";
+import { networkUrls } from "../server/bind.js";
+import { startHub } from "../server/server.js";
+import { ensureBuilt, supervise } from "./ui.js";
+/**
+ * `kraftwerk daemon` — the machine's kraftwerk: one process serving every
+ * open workspace, each at `<slug>.localhost:<port>` (and its own port, when
+ * free). `kraftwerk ui` in a workspace folder opens it there; `kraftwerk
+ * workspaces stop <root>` closes it; the daemon reopens what was open when it
+ * starts again. Runs in the foreground, restarted by a supervisor after a
+ * self-update like `kraftwerk ui`.
+ */
+export async function runDaemon(opts) {
+    if (opts.lan)
+        process.env.KRAFTWERK_UI_HOST ||= "0.0.0.0";
+    if (process.env.KRAFTWERK_UI_SUPERVISED !== "1")
+        return supervise(["daemon", ...(opts.port ? ["--port", opts.port] : [])], "the daemon");
+    const running = await findDaemon();
+    if (running && running.pid !== process.pid) {
+        console.error(chalk.red(`✖ a kraftwerk daemon already runs (pid ${running.pid}, port ${running.port})`));
+        process.exit(1);
+    }
+    const port = Number(opts.port ?? process.env.KRAFTWERK_DAEMON_PORT ?? DAEMON_PORT);
+    const reopen = await lastOpenRoots();
+    const hub = await startHub({
+        port,
+        staticDir: ensureBuilt(),
+        daemon: true,
+        onChange: (h) => writeDaemonFile(h.port, h.list().map((o) => o.root)),
+    });
+    await writeDaemonFile(hub.port, []);
+    for (const root of reopen) {
+        try {
+            await hub.open(root);
+        }
+        catch (err) {
+            console.log(`${chalk.yellow("⚠")} not reopened: ${tildify(root)} — ${err.message}`);
+        }
+    }
+    console.log(`${chalk.green("✔")} kraftwerk daemon on ${chalk.cyan(`http://localhost:${hub.port}`)} ${chalk.dim(`(pid ${process.pid})`)}`);
+    for (const o of hub.list())
+        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"));
+    const lan = networkUrls(hub.port);
+    if (lan.length)
+        console.log(`${chalk.green("✔")} On your network: ${lan.map((u) => chalk.cyan(u)).join(", ")} ${chalk.dim("(add /w/<slug>/; devices pair first)")}`);
+}
+export function registerDaemonCommand(program) {
+    program
+        .command("daemon")
+        .description("Run the machine's kraftwerk: one process serving every open workspace at <slug>.localhost")
+        .option("--port <port>", `Port (default: KRAFTWERK_DAEMON_PORT, else ${DAEMON_PORT})`)
+        .option("--lan", "Listen on the network too, for paired devices")
+        .action(async (opts) => {
+        await runDaemon(opts);
+    });
+}

package/dist/cli/devices.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+/**
+ * `kraftwerk devices` — other machines (a phone, a second laptop, an app)
+ * that may use this machine's kraftwerk. One pairing covers every
+ * workspace here; the store is ~/.kraftwerk/devices.json.
+ *
+ *   kraftwerk devices                list paired devices
+ *   kraftwerk devices pair           a one-time code to pair one (10 minutes)
+ *   kraftwerk devices revoke <id>    unpair one: its token stops working at once
+ *
+ * A device reaches this machine when the UI listens on the network:
+ * `kraftwerk ui --lan` (or through a tunnel, see `kraftwerk tunnel`).
+ */
+export declare function registerDevicesCommands(program: Command): void;

package/dist/cli/devices.js

@@ -0,0 +1,53 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import { createPairCode, listDevices, PAIR_CODE_TTL_MS, revokeDevice } from "../core/devices.js";
+import { fmtAgo } from "./workspaces.js";
+/**
+ * `kraftwerk devices` — other machines (a phone, a second laptop, an app)
+ * that may use this machine's kraftwerk. One pairing covers every
+ * workspace here; the store is ~/.kraftwerk/devices.json.
+ *
+ *   kraftwerk devices                list paired devices
+ *   kraftwerk devices pair           a one-time code to pair one (10 minutes)
+ *   kraftwerk devices revoke <id>    unpair one: its token stops working at once
+ *
+ * A device reaches this machine when the UI listens on the network:
+ * `kraftwerk ui --lan` (or through a tunnel, see `kraftwerk tunnel`).
+ */
+export function registerDevicesCommands(program) {
+    const devices = program.command("devices").description("Paired devices: list, pair one, revoke one");
+    devices
+        .command("list", { isDefault: true })
+        .description("List paired devices")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        const list = await listDevices();
+        if (opts.json)
+            return void console.log(JSON.stringify(list, null, 2));
+        if (list.length === 0)
+            return void console.log(chalk.dim("No paired devices. `kraftwerk devices pair` makes a code for one."));
+        const table = new Table({ head: ["id", "name", "paired", "last seen"].map((h) => chalk.bold(h)) });
+        for (const d of list)
+            table.push([chalk.cyan(d.id), d.name, chalk.dim(fmtAgo(d.createdAt)), chalk.dim(d.lastSeenAt ? fmtAgo(d.lastSeenAt) : "never")]);
+        console.log(table.toString());
+    });
+    devices
+        .command("pair")
+        .description(`A one-time pairing code, valid ${PAIR_CODE_TTL_MS / 60_000} minutes`)
+        .action(async () => {
+        const { code } = await createPairCode();
+        console.log(`${chalk.green("✔")} pairing code ${chalk.bold.cyan(code)} ${chalk.dim(`— valid ${PAIR_CODE_TTL_MS / 60_000} minutes, once`)}`);
+        console.log(chalk.dim("Open kraftwerk on the device (start the UI with `kraftwerk ui --lan` to reach it on your network) and enter the code."));
+    });
+    devices
+        .command("revoke")
+        .description("Unpair a device: its token stops working at once")
+        .argument("<id>", "Device id as `kraftwerk devices` lists it")
+        .action(async (id) => {
+        if (!(await revokeDevice(id))) {
+            console.error(chalk.red(`No paired device "${id}".`));
+            process.exit(1);
+        }
+        console.log(`${chalk.green("✔")} unpaired ${chalk.cyan(id)}`);
+    });
+}

package/dist/cli/doctor-legacy.js

@@ -78,14 +78,22 @@ async function oldRunFolders(outputDir) {
         ? [{ level: "info", label: `${old.length} run(s) in the old location`, detail: `${tildify(outputDir)}/run-* — still listed; new runs go to runs/, move them there to tidy up` }]
         : [];
 }
+/** kraftwerk.yml keys from the Cloudflare Tunnel (removed in 0.65): the loader ignores them (`legacyKeys`). */
+function oldConfigKeys(ws) {
+    const keys = ws.legacyKeys ?? [];
+    return keys.length
+        ? [{ level: "info", label: "kraftwerk.yml still has public:/tunnel:", detail: `${keys.map((k) => `${k}:`).join(", ")} — the Cloudflare Tunnel was removed in 0.65 and these keys are ignored; delete them` }]
+        : [];
+}
 export async function legacyFindings(ws, version) {
     const output = existsSync(ws.outputDir) ? ws.outputDir : "";
     const found = [
         ...(await olderInstances(version)),
         ...installsOnPath(),
         ...(await oldRegistry()),
+        ...oldConfigKeys(ws),
         ...(output ? await oldChatScopes(output) : []),
         ...(output ? await oldRunFolders(output) : []),
     ];
-    return found.length ? found : [{ level: "ok", label: "no legacy leftovers", detail: "no older servers, installs, registry or data formats" }];
+    return found.length ? found : [{ level: "ok", label: "no legacy leftovers", detail: "no older servers, installs, registry, config keys or data formats" }];
 }

package/dist/cli/doctor.js

@@ -2,11 +2,13 @@ import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { cloudFor, ignoreEntryFor, isDir, publicHostFor, reposRootFor, resolveWorkspace, tunnelFor } from "../config.js";
+import { cloudFor, 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";
 import { legacyFindings, versionLt } from "./doctor-legacy.js";
+import { listDevices } from "../core/devices.js";
+import { slugClashes } from "../core/instances.js";
 const ICONS = {
     ok: chalk.green("✔"),
     warn: chalk.yellow("⚠"),
@@ -71,6 +73,13 @@ export async function runDoctor(cwd) {
         process.exit(1);
     }
     report("info", `Project root: ${project.root}`, project.configPath ? path.basename(project.configPath) : "no kraftwerk.yml (fallback: workflows folder or .git)");
+    // The slug is the workspace's address on this machine; two workspaces cannot share one.
+    const slug = workspaceSlug(project);
+    const clash = await slugClashes(slug, project.root);
+    if (clash.length)
+        report("warn", `slug: ${slug}`, `also used by ${clash.map((r) => r.root).join(", ")} — set \`slug:\` in one kraftwerk.yml`);
+    else
+        report("ok", `slug: ${slug}`, project.config.slug ? "from kraftwerk.yml" : "the folder name — `slug:` in kraftwerk.yml sets another");
     // Project config: well-formed (guaranteed by the parse above) and the
     // configured paths actually exist.
     if (!project.configPath) {
@@ -79,7 +88,7 @@ export async function runDoctor(cwd) {
     else {
         const cfg = project.config;
         const keys = Object.keys(cfg);
-        // Blocks (git, repos, vibeables, projects, tunnel) print as their keys, not [object Object].
+        // Blocks (git, repos, vibeables, projects, cloud) print as their keys, not [object Object].
         const show = (v) => typeof v === "object" && v !== null
             ? Array.isArray(v)
                 ? `[${v.length}]`
@@ -112,7 +121,7 @@ export async function runDoctor(cwd) {
         report("ok", `${DOTENV_FILE}: ${names.length} variable(s) loaded`, names.join(", ") || "empty");
     }
     else {
-        report("info", `no ${DOTENV_FILE}`, "variables for agents, workflows and the tunnel can live there — loaded on every start and restart");
+        report("info", `no ${DOTENV_FILE}`, "variables for agents and workflows can live there — loaded on every start and restart");
     }
     // Repositories: the clones root must stay out of the workspace git. git
     // itself decides — that covers worktrees (.git is a file), a workspace
@@ -131,33 +140,6 @@ export async function runDoctor(cwd) {
         else
             report("ok", label, "not inside a git repository");
     }
-    // Public hostname + Cloudflare Tunnel. The UI has no login of its own, so
-    // a tunnel without Access verification is worth a warning every time.
-    const publicHost = publicHostFor(project);
-    const tunnel = tunnelFor(project);
-    if (publicHost && !tunnel)
-        report("info", `public: ${publicHost}`, "served when a tunnel or reverse proxy delivers that Host");
-    if (tunnel) {
-        const cloudflared = cliVersion("cloudflared");
-        if (cloudflared)
-            report("ok", `cloudflared`, cloudflared);
-        else {
-            report("fail", "cloudflared missing", "needed by tunnel: — brew install cloudflared (or see developers.cloudflare.com)");
-            failures++;
-        }
-        if (tunnel.name)
-            report("ok", `tunnel: ${tunnel.name} → ${publicHost}`, `cloudflared tunnel run --url http://127.0.0.1:${project.config.port ?? 1981} ${tunnel.name}`);
-        else if (process.env.TUNNEL_TOKEN)
-            report("ok", `tunnel: dashboard-managed → ${publicHost}`, "TUNNEL_TOKEN is set");
-        else {
-            report("fail", "tunnel: nothing to run", "set tunnel.name (locally-managed) or the TUNNEL_TOKEN env var (dashboard-managed)");
-            failures++;
-        }
-        if (tunnel.access)
-            report("ok", "tunnel.access", `tokens verified against ${tunnel.access.team}.cloudflareaccess.com`);
-        else
-            report("warn", "tunnel without access", "the UI has no login of its own — put a Cloudflare Access policy on the hostname and set tunnel.access so a removed policy fails closed");
-    }
     // Cloud manager: registration is best-effort at runtime, so doctor only says what would happen.
     const cloud = cloudFor(project);
     if (cloud) {
@@ -223,6 +205,11 @@ export async function runDoctor(cwd) {
         else
             report("warn", `${e.workflow.name}: env missing`, missing.join(", "));
     }
+    // Devices: who may use this machine's kraftwerk from elsewhere.
+    const devices = await listDevices();
+    if (process.env.KRAFTWERK_UI_TRUST_NETWORK === "1")
+        report("warn", "KRAFTWERK_UI_TRUST_NETWORK=1", "anyone who reaches the UI over the network uses it without pairing — unset it and pair devices instead (`kraftwerk devices pair`)");
+    report("info", devices.length ? `${devices.length} paired device(s)` : "no paired devices", devices.length ? devices.map((d) => d.name).join(", ") : "a phone or another computer can use kraftwerk once paired: `kraftwerk ui --lan`, then `kraftwerk devices pair`");
     // Legacy: what older versions left behind, and what still runs or is installed at one.
     for (const f of await legacyFindings(project, pkg.version))
         report(f.level, f.label, f.detail);

package/dist/cli/init.js

@@ -16,6 +16,7 @@ const configTemplate = (name) => `# yaml-language-server: $schema=${CONFIG_SCHEM
 # kraftwerk project config — also marks the project root for the CLI.
 # All fields optional. Docs: https://github.com/NETNODEAG/kraftwerk
 name: ${JSON.stringify(name)}   # display name, shown in the inspector header + browser tab
+# slug: my-team   # this workspace's address on this machine (my-team.localhost); default: the folder name
 icon: "⚡"   # emoji shown as the inspector favicon
 port: 1981   # port \`kraftwerk ui\` listens on
 workflows: ${DATA_DIR}/workflows   # where workflows live
@@ -27,12 +28,6 @@ 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)
-# public: https://kw.example.com  # hostname the inspector is reached at through a tunnel or reverse proxy
-# tunnel:                         # Cloudflare Tunnel run by \`kraftwerk ui\` (needs public:; put a Cloudflare Access policy on the hostname — the UI has no login of its own)
-#   name: kraftwerk               # locally-managed tunnel (cloudflared tunnel create/route dns); omit and export TUNNEL_TOKEN for a dashboard-managed one
-#   access:                       # verify the Access login on every request via public: (team = Zero Trust team name, aud = the application's audience tag)
-#     team: my-team
-#     aud: 4714c1358e65fe4b408ad6d432a5f878f08194bdb4752441fd56faefa9b2b6f2
 # 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)
 `;