@netnodeag/kraftwerk 0.65.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)
@@ -182,19 +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, and state-changing requests are refused when `Origin` names a
-different host.
+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
 
@@ -203,10 +268,15 @@ 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
+`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

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/doctor.js

@@ -2,12 +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, reposRootFor, resolveWorkspace } 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("⚠"),
@@ -72,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) {

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

package/dist/cli/kraftwerk.js

@@ -18,6 +18,7 @@ import { registerRepoCommands } from "./repos.js";
 import { registerVibeableCommands } from "./vibeables.js";
 import { registerTrashCommands } from "./trash.js";
 import { registerDevicesCommands } from "./devices.js";
+import { registerDaemonCommand } from "./daemon.js";
 import { registerJournalCommands } from "./journal.js";
 import { applyDotenv } from "../dotenv.js";
 import { resolveWorkspace } from "../config.js";
@@ -41,6 +42,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk journal <agent> [entry] an agent's memory across sessions: print it, add a line
  *   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 doctor                  preflight: harness CLIs, docker, workflows, env
  *   kraftwerk validate [paths...]     validate without executing
  *
@@ -292,6 +294,7 @@ registerRepoCommands(program);
 registerVibeableCommands(program);
 registerTrashCommands(program);
 registerDevicesCommands(program);
+registerDaemonCommand(program);
 registerJournalCommands(program);
 program
     .command("ui")
@@ -299,6 +302,7 @@ program
     .option("--port <port>", "Port for the web UI (default: kraftwerk.yml `port`, else 1981)")
     .option("--output <dir>", "Output directory to inspect (default: the project's output dir)")
     .option("--lan", "Listen on the network too, so paired devices (a phone) reach it — others get a pairing screen")
+    .option("--standalone", "Run a server of its own even when the kraftwerk daemon runs")
     .action(async (opts) => {
     await runUi(process.cwd(), opts);
 });

package/dist/cli/ui.d.ts

@@ -1,5 +1,13 @@
+/**
+ * Published packages ship web/dist. A dev checkout builds it on
+ * first use (and after frontend edits: `npm run build` in web/).
+ */
+export declare function ensureBuilt(): string;
 export declare function runUi(cwd: string, opts: {
     port?: string;
     output?: string;
     lan?: boolean;
+    standalone?: boolean;
 }): Promise<void>;
+/** The respawn loop for any long-running kraftwerk process (`ui`, `daemon`): see superviseUi. */
+export declare function supervise(argv: string[], what: string): Promise<void>;

package/dist/cli/ui.js

@@ -4,7 +4,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import chalk from "chalk";
-import { absolutePath, resolveWorkspace } from "../config.js";
+import { absolutePath, resolveWorkspace, workspaceSlug } from "../config.js";
+import { slugClashes } from "../core/instances.js";
+import { daemonCall, findDaemon } from "../core/daemon.js";
 import { selfCommand } from "../core/self-command.js";
 import { RESTART_EXIT_CODE, startInspector } from "../server/server.js";
 import { networkUrls } from "../server/bind.js";
@@ -26,7 +28,10 @@ const packageRoot = () => path.join(path.dirname(fileURLToPath(import.meta.url))
  * Published packages ship web/dist. A dev checkout builds it on
  * first use (and after frontend edits: `npm run build` in web/).
  */
-function ensureBuilt() {
+export function ensureBuilt() {
+    // Another build of the web UI (tests serve a stub; a dev setup may point at its own).
+    if (process.env.KRAFTWERK_WEB_DIR)
+        return path.resolve(process.env.KRAFTWERK_WEB_DIR);
     const web = path.join(packageRoot(), "web");
     const dist = path.join(web, "dist");
     if (existsSync(path.join(dist, "index.html")))
@@ -49,6 +54,23 @@ function ensureBuilt() {
     return dist;
 }
 export async function runUi(cwd, opts) {
+    // The machine runs a daemon: hand it this workspace, it serves it next to the others.
+    if (!opts.standalone && !opts.port && !opts.output && !opts.lan && process.env.KRAFTWERK_UI_SUPERVISED !== "1") {
+        const daemon = await findDaemon();
+        if (daemon) {
+            const project = await resolveWorkspace(cwd);
+            const r = await daemonCall(daemon.port, "open", project.root);
+            if (!r.ok) {
+                console.error(chalk.red(`✖ the kraftwerk daemon refused: ${r.data.error ?? r.status}`));
+                process.exit(1);
+            }
+            console.log(`${chalk.green("✔")} Kraftwerk UI: ${chalk.cyan(r.data.url)} ${chalk.dim(`(served by the kraftwerk daemon, pid ${daemon.pid})`)}`);
+            if (r.data.aliasPort)
+                console.log(chalk.dim(`  also at http://localhost:${r.data.aliasPort}`));
+            console.log(chalk.dim("  `kraftwerk workspaces stop .` closes it there; `kraftwerk ui --standalone` runs a server of its own instead."));
+            return;
+        }
+    }
     // The server reads its bind address when it starts — in the supervised child, which inherits this.
     if (opts.lan)
         process.env.KRAFTWERK_UI_HOST ||= "0.0.0.0";
@@ -60,6 +82,11 @@ export async function runUi(cwd, opts) {
     // Port precedence: --port flag > kraftwerk.yml `port` > 1981.
     const port = opts.port ? Number(opts.port) : (project.config.port ?? 1981);
     await startInspector({ outputDir, staticDir, port, root: project.root });
+    // Two workspaces with one slug would share an address once one kraftwerk serves them all.
+    const slug = workspaceSlug(project);
+    const clash = await slugClashes(slug, project.root);
+    if (clash.length)
+        console.log(`${chalk.yellow("⚠")} slug "${slug}" is also used by ${clash.map((r) => r.root).join(", ")} — set \`slug:\` in one kraftwerk.yml so each workspace keeps its own address`);
     console.log(`${chalk.green("✔")} Kraftwerk UI: ${chalk.cyan(`http://localhost:${port}`)} ` +
         chalk.dim(`(output: ${outputDir})`));
     const lan = networkUrls(port);
@@ -78,11 +105,11 @@ export async function runUi(cwd, opts) {
  * foreground group and reaches both anyway.
  */
 async function superviseUi(opts) {
-    const { cmd, args } = selfCommand([
-        "ui",
-        ...(opts.port ? ["--port", opts.port] : []),
-        ...(opts.output ? ["--output", opts.output] : []),
-    ]);
+    return supervise(["ui", "--standalone", ...(opts.port ? ["--port", opts.port] : []), ...(opts.output ? ["--output", opts.output] : [])], "the UI");
+}
+/** The respawn loop for any long-running kraftwerk process (`ui`, `daemon`): see superviseUi. */
+export async function supervise(argv, what) {
+    const { cmd, args } = selfCommand(argv);
     for (;;) {
         const child = spawn(cmd, args, {
             stdio: "inherit",
@@ -104,6 +131,6 @@ async function superviseUi(opts) {
                 process.exit(128 + (os.constants.signals[result.signal] ?? 1));
             process.exit(result.code ?? 1);
         }
-        console.log(chalk.dim("↻ relaunching the UI with the current install ..."));
+        console.log(chalk.dim(`↻ relaunching ${what} with the current install ...`));
     }
 }

package/dist/cli/workspaces.js

@@ -50,7 +50,9 @@ async function resolveRef(ref, needRoot = true) {
         e.root === ref ||
         e.name === ref ||
         (e.root && path.basename(e.root) === ref) ||
-        e.url === port);
+        e.url === port ||
+        // A daemon's workspace by its slug: <slug>.localhost.
+        e.url.startsWith(`http://${ref}.localhost:`));
     if (hits.length === 1)
         return hits[0];
     if (hits.length === 0) {
@@ -117,8 +119,8 @@ export function registerWorkspaceCommands(program) {
     });
     workspaces
         .command("stop")
-        .description("Stop a running UI (SIGTERM to its server; works for terminal-started ones too)")
-        .argument("<ref>", "Workspace name, folder name, root path, or port")
+        .description("Stop a running UI (closes it in the kraftwerk daemon, or SIGTERM to a server of its own)")
+        .argument("<ref>", "Workspace name, slug, folder name, root path, or port")
         .action(async (ref) => {
         const entry = await resolveRef(ref, false);
         if (!entry.live) {

package/dist/client/index.d.ts

@@ -63,6 +63,12 @@ export declare function errorOf(body: unknown): string | undefined;
 export interface ClientOptions {
     /** Where the server is; "" (the default) is the page's own origin. */
     baseUrl?: string;
+    /**
+     * The workspace (its slug) to talk to, through the `/w/<slug>` path form.
+     * Leave it out when the address already names one (`<slug>.localhost`, or
+     * a server's own port).
+     */
+    workspace?: string;
     fetch?: typeof fetch;
     /**
      * A paired device's token (from `devices.pair`), sent as `Authorization:
@@ -81,5 +87,7 @@ export interface Client {
     onChange(fn: () => void): () => void;
     /** The token the client was created with, if any (the socket sends it too). */
     readonly token?: string;
+    /** Where routes live: baseUrl plus the workspace's `/w/<slug>` prefix. */
+    readonly baseUrl: string;
 }
 export declare function createClient(opts?: ClientOptions): Client;

package/dist/client/index.js

@@ -17,7 +17,7 @@ export function errorOf(body) {
     return typeof error === "string" && error ? error : undefined;
 }
 export function createClient(opts = {}) {
-    const base = (opts.baseUrl ?? "").replace(/\/+$/, "");
+    const base = (opts.baseUrl ?? "").replace(/\/+$/, "") + (opts.workspace ? `/w/${encodeURIComponent(opts.workspace)}` : "");
     const doFetch = opts.fetch ?? ((...a) => fetch(...a));
     const changeFns = new Set();
     const url = (name, input = {}) => {
@@ -66,6 +66,7 @@ export function createClient(opts = {}) {
     };
     return {
         token: opts.token,
+        baseUrl: base,
         onChange(fn) {
             changeFns.add(fn);
             return () => changeFns.delete(fn);

package/dist/client/live.d.ts

@@ -25,9 +25,8 @@ export interface Live {
     close(): void;
 }
 export interface LiveOptions {
-    /** The HTTP client for fallbacks; its baseUrl is the server. */
+    /** The HTTP client: its baseUrl (workspace prefix included) is where the socket connects too. */
     client: Client;
-    baseUrl?: string;
     WebSocket?: typeof WebSocket;
     EventSource?: typeof EventSource;
 }

package/dist/client/live.js

@@ -12,7 +12,8 @@ export function createLive(opts) {
     let retry;
     let counter = 0;
     const socketUrl = () => {
-        const base = opts.baseUrl ?? (typeof location === "undefined" ? "" : location.origin);
+        // The client's base carries the workspace prefix; a relative one is on this page's origin.
+        const base = /^https?:/.test(client.baseUrl) ? client.baseUrl : (typeof location === "undefined" ? "" : location.origin) + client.baseUrl;
         // A browser's socket carries the device cookie; other runtimes cannot send headers on a WebSocket, so the token rides in the query.
         return `${base.replace(/^http/, "ws").replace(/\/+$/, "")}/api/ws${client.token ? `?token=${encodeURIComponent(client.token)}` : ""}`;
     };

package/dist/client/routes.d.ts

@@ -62,6 +62,9 @@ export declare const ROUTES: {
     readonly "git.pull": readonly ["POST", "/api/git/pull"];
     readonly "git.push": readonly ["POST", "/api/git/push"];
     readonly "git.status": readonly ["GET", "/api/git"];
+    readonly "hub.close": readonly ["POST", "/api/hub/close"];
+    readonly "hub.list": readonly ["GET", "/api/hub"];
+    readonly "hub.open": readonly ["POST", "/api/hub/open"];
     readonly "knowledge.concept": readonly ["GET", "/api/knowledge/:bundle/concept"];
     readonly "knowledge.create": readonly ["POST", "/api/knowledge"];
     readonly "knowledge.delete": readonly ["DELETE", "/api/knowledge/:bundle"];

package/dist/client/routes.js

@@ -63,6 +63,9 @@ export const ROUTES = {
     "git.pull": ["POST", "/api/git/pull"],
     "git.push": ["POST", "/api/git/push"],
     "git.status": ["GET", "/api/git"],
+    "hub.close": ["POST", "/api/hub/close"],
+    "hub.list": ["GET", "/api/hub"],
+    "hub.open": ["POST", "/api/hub/open"],
     "knowledge.concept": ["GET", "/api/knowledge/:bundle/concept"],
     "knowledge.create": ["POST", "/api/knowledge"],
     "knowledge.delete": ["DELETE", "/api/knowledge/:bundle"],

package/dist/config.d.ts

@@ -12,6 +12,7 @@
  *   name: my-project           # display name (inspector header, "environment")
  *   icon: "⚡"                  # emoji shown as inspector favicon
  *   color: "#c2410c"           # accent for this workspace in the switcher (default: derived from the root)
+ *   slug: team-blau            # this workspace's address (team-blau.localhost); default: the folder name
  *   port: 1981                 # port `kraftwerk ui` listens on
  *   workflows: src/workflows   # workflows root, relative to the file
  *   output: output             # run-artifact directory, relative to the file
@@ -166,6 +167,12 @@ export interface SwitcherEntry {
 export interface WorkspaceConfig {
     /** Display name of the project ("environment"), shown in the inspector header. */
     name?: string;
+    /**
+     * The workspace's address on this machine: `<slug>.localhost`, `/w/<slug>/`.
+     * Unique per machine. Default: the folder name (see workspaceSlug). The
+     * name above may change freely; the slug only when you mean to move it.
+     */
+    slug?: string;
     /** Emoji used as the inspector favicon (browser-tab icon). */
     icon?: string;
     /** Accent colour (#rgb / #rrggbb) for this workspace in the switcher. Default: derived from the root path. */
@@ -234,3 +241,12 @@ export declare const resolveProject: typeof resolveWorkspace;
 export type Project = ResolvedWorkspace;
 /** @deprecated Use `WorkspaceConfig`. */
 export type ProjectConfig = WorkspaceConfig;
+/** A folder name as a slug: "Team Blau (2024)" → "team-blau-2024". */
+export declare function slugFromFolder(folder: string): string;
+/** The workspace's slug: kraftwerk.yml `slug`, else its folder name made into one. */
+export declare function workspaceSlug(ws: {
+    root: string;
+    config: {
+        slug?: string;
+    };
+}): string;

package/dist/config.js

@@ -16,6 +16,7 @@ import { parse } from "yaml";
  *   name: my-project           # display name (inspector header, "environment")
  *   icon: "⚡"                  # emoji shown as inspector favicon
  *   color: "#c2410c"           # accent for this workspace in the switcher (default: derived from the root)
+ *   slug: team-blau            # this workspace's address (team-blau.localhost); default: the folder name
  *   port: 1981                 # port `kraftwerk ui` listens on
  *   workflows: src/workflows   # workflows root, relative to the file
  *   output: output             # run-artifact directory, relative to the file
@@ -194,7 +195,25 @@ export async function resolveWorkspace(cwd) {
 }
 /** @deprecated Renamed: a kraftwerk.yml root is a workspace (projects are the folders inside). Use `resolveWorkspace`. */
 export const resolveProject = resolveWorkspace;
-const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "cloud"];
+/** A workspace slug: a DNS label, so `<slug>.localhost` is a valid host name. */
+const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/** A folder name as a slug: "Team Blau (2024)" → "team-blau-2024". */
+export function slugFromFolder(folder) {
+    const s = folder
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 63)
+        .replace(/-+$/, "");
+    return s || "workspace";
+}
+/** The workspace's slug: kraftwerk.yml `slug`, else its folder name made into one. */
+export function workspaceSlug(ws) {
+    return ws.config.slug ?? slugFromFolder(path.basename(ws.root));
+}
+const KNOWN_KEYS = ["name", "slug", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "cloud"];
 /**
  * Keys an older kraftwerk understood and this one ignores, so the files
  * that still carry them keep loading: `public:` and `tunnel:` (the
@@ -224,6 +243,9 @@ async function loadConfig(configPath) {
         if (!known.includes(key)) {
             throw new Error(`${path.basename(configPath)}: unknown key "${key}" (allowed: ${known.join(", ")})`);
         }
+        if (key === "slug" && (typeof config[key] !== "string" || !SLUG_RE.test(config[key]))) {
+            throw new Error(`${path.basename(configPath)}: slug must be lowercase letters, digits and dashes, starting with a letter or digit (at most 63)`);
+        }
         if (key === "port") {
             if (typeof config[key] !== "number" || !Number.isInteger(config[key])) {
                 throw new Error(`${path.basename(configPath)}: port must be an integer`);

package/dist/core/chat/pi.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { workspaceEnv } from "../env.js";
 const clip = (raw) => {
     const oneLine = String(raw ?? "").replace(/\s+/g, " ").trim();
     return oneLine.length > 120 ? `${oneLine.slice(0, 120)}…` : oneLine;
@@ -23,7 +24,7 @@ export function startPiBackend(cwd, hooks, tuning = {}) {
                 const proc = spawn("pi", ["-p", "--mode", "json", "--session-id", sessionId, ...tuningArgs], {
                     cwd,
                     stdio: ["pipe", "pipe", "pipe"],
-                    env: process.env,
+                    env: workspaceEnv(),
                 });
                 child = proc;
                 proc.stdin.write(text);