@netnodeag/kraftwerk 0.46.2 → 0.47.0

package/README.md

@@ -164,6 +164,8 @@ 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)
 ```
 
 The inspector binds `127.0.0.1` — it has no authentication of its own and
@@ -177,8 +179,9 @@ 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.
+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 kraftwerk.yml project config
 
@@ -187,6 +190,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.
+`public:` and `tunnel:` expose the inspector through a
+[Cloudflare Tunnel](#inspector-through-a-cloudflare-tunnel).
 
 `switcher:` links other kraftwerk workspaces from the inspector header. The
 workspace name becomes a dropdown listing them:
@@ -283,6 +288,111 @@ 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 projects
+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.
+
 ## Persistent agents
 
 The inspector's "agents" screen turns chat agents into persistent teammates. An

package/dist/cli/doctor.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { ignoreEntryFor, isDir, reposRootFor, resolveProject } from "../config.js";
+import { ignoreEntryFor, isDir, publicHostFor, reposRootFor, resolveProject, tunnelFor } from "../config.js";
 import { discoverWorkflows } from "../discover.js";
 import { missingEnv } from "../yaml.js";
 const ICONS = {
@@ -123,6 +123,33 @@ 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");
+    }
     const found = project.workflowsRoot ? await discoverWorkflows(cwd) : [];
     if (!project.workflowsRoot) {
         report("warn", "no workflows root", "expected src/workflows/ or workflows/ — `kraftwerk init` scaffolds one");

package/dist/cli/init.js

@@ -25,6 +25,12 @@ skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packag
 # repos:                          # git repositories the agents work on (uncomment both lines to enable)
 #   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)
+# 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
 `;
 const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
 name: hello

package/dist/cli/kraftwerk.js

@@ -15,6 +15,7 @@ import { registerKnowledgeCommands } from "./knowledge.js";
 import { registerProjectCommands } from "./projects.js";
 import { registerRepoCommands } from "./repos.js";
 import { registerVibeableCommands } from "./vibeables.js";
+import { registerTunnelCommands } from "./tunnel.js";
 import { registerRoutineCommands } from "./routines.js";
 import { listRuns, showRun } from "./runs.js";
 import { runUi } from "./ui.js";
@@ -30,6 +31,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
  *   kraftwerk projects ...            known projects on this machine (list/start/forget)
  *   kraftwerk repos ...               repositories the agents work on (list/add/update/remove)
+ *   kraftwerk tunnel [setup <host>]   Cloudflare Tunnel to the inspector: run it alone, or set one up
  *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
  *   kraftwerk validate [paths...]     validate without executing
  *
@@ -270,6 +272,7 @@ registerRoutineCommands(program);
 registerProjectCommands(program);
 registerRepoCommands(program);
 registerVibeableCommands(program);
+registerTunnelCommands(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/cli/tunnel.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type Project } from "../config.js";
+export interface RunningTunnel {
+    stop(): void;
+    /** Settles when the tunnel was stopped, or gave up on a cloudflared that keeps dying. */
+    done: Promise<"stopped" | "failed">;
+}
+/** Start cloudflared for the project's tunnel, or return undefined (nothing to run, or told why not). */
+export declare function startTunnel(project: Project, port: number): RunningTunnel | undefined;
+export declare function registerTunnelCommands(program: Command): void;

package/dist/cli/tunnel.js

@@ -0,0 +1,280 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import { parseDocument } from "yaml";
+import { parsePublic, publicHostFor, resolveProject, tunnelFor } from "../config.js";
+/**
+ * Cloudflare Tunnel next to the inspector. `kraftwerk ui` runs cloudflared
+ * as a sibling of the server so the loopback bind is reachable at the
+ * project's public hostname without opening a port. The tunnel itself is
+ * created once, by `kraftwerk tunnel setup` or by hand:
+ *
+ *   locally-managed      cloudflared tunnel login
+ *                        cloudflared tunnel create kraftwerk
+ *                        cloudflared tunnel route dns kraftwerk kw.example.com
+ *                        → tunnel: { name: kraftwerk }; everything routes to the inspector port
+ *   dashboard-managed    create the tunnel in Zero Trust → Networks → Tunnels, route the
+ *                        public hostname to http://localhost:<port> there, export TUNNEL_TOKEN
+ *                        → tunnel: {} ; cloudflared reads the token from the environment
+ *
+ * cloudflared reconnects on its own; this only respawns it when the process
+ * itself dies, after a pause. A process that keeps dying right after launch
+ * (no login, unknown tunnel name) is a configuration problem: after a few
+ * such exits the tunnel gives up and says so, and the UI stays local.
+ *
+ *   kraftwerk tunnel                   run the configured tunnel alone (the UI runs elsewhere)
+ *   kraftwerk tunnel setup <hostname>  login, create, route dns, write public: + tunnel.name
+ */
+const RESPAWN_DELAY = 5_000;
+/** An exit this soon after launch is a configuration problem, not a hiccup. */
+const FAST_EXIT = 10_000;
+const MAX_FAST_EXITS = 3;
+/** Start cloudflared for the project's tunnel, or return undefined (nothing to run, or told why not). */
+export function startTunnel(project, port) {
+    const tunnel = tunnelFor(project);
+    if (!tunnel)
+        return undefined;
+    const host = publicHostFor(project);
+    let args;
+    if (tunnel.name) {
+        args = ["tunnel", "--no-autoupdate", "run", "--url", `http://127.0.0.1:${port}`, tunnel.name];
+    }
+    else if (process.env.TUNNEL_TOKEN) {
+        args = ["tunnel", "--no-autoupdate", "run"];
+    }
+    else {
+        console.error(`${chalk.red("✖")} tunnel: nothing to run — set ${chalk.bold("tunnel.name")} in kraftwerk.yml (locally-managed) ` +
+            `or the ${chalk.bold("TUNNEL_TOKEN")} environment variable (dashboard-managed). The UI stays local.`);
+        return undefined;
+    }
+    let child;
+    let stopped = false;
+    let timer;
+    let fastExits = 0;
+    let settle = () => { };
+    const done = new Promise((resolve) => (settle = resolve));
+    const launch = () => {
+        const startedAt = Date.now();
+        console.log(`${chalk.dim("↗")} tunnel: ${tunnel.name ? `running ${chalk.bold(tunnel.name)}` : "running the dashboard-managed tunnel"}` +
+            chalk.dim(` → https://${host} → http://127.0.0.1:${port}`));
+        child = spawn("cloudflared", args, { stdio: ["ignore", "pipe", "pipe"] });
+        // cloudflared logs on stderr, one line per event; keep them recognisable.
+        const relay = (chunk) => {
+            for (const line of chunk.toString().split("\n"))
+                if (line.trim())
+                    console.log(chalk.dim(`  cloudflared │ ${line}`));
+        };
+        child.stdout?.on("data", relay);
+        child.stderr?.on("data", relay);
+        child.once("error", (err) => {
+            stopped = true;
+            if (err.code === "ENOENT") {
+                console.error(`${chalk.red("✖")} tunnel: cloudflared not found — brew install cloudflared (or see developers.cloudflare.com). The UI stays local.`);
+            }
+            else {
+                console.error(`${chalk.red("✖")} tunnel: cannot start cloudflared: ${err.message}`);
+            }
+            settle("failed");
+        });
+        // "close", not "exit": the last log lines are still in flight when the
+        // process ends, and they are what explains a failed launch.
+        child.once("close", (code, signal) => {
+            child = undefined;
+            if (stopped)
+                return settle("stopped");
+            fastExits = Date.now() - startedAt < FAST_EXIT ? fastExits + 1 : 0;
+            if (fastExits >= MAX_FAST_EXITS) {
+                console.error(`${chalk.red("✖")} tunnel: cloudflared exited ${MAX_FAST_EXITS} times right after launch — giving up. ` +
+                    `Check the messages above (cloudflared tunnel login? does the tunnel exist?), then restart the UI. The UI stays local.`);
+                return settle("failed");
+            }
+            console.error(`${chalk.red("✖")} tunnel: cloudflared exited (${signal ?? `code ${code}`}) — retrying in ${RESPAWN_DELAY / 1000}s`);
+            timer = setTimeout(launch, RESPAWN_DELAY);
+        });
+    };
+    launch();
+    return {
+        done,
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            if (child)
+                child.kill("SIGTERM");
+            else
+                settle("stopped");
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// CLI
+const die = (msg, code = 1) => {
+    console.error(chalk.red(msg));
+    process.exit(code);
+};
+/** cloudflared's version line, or undefined when the binary is not on PATH. */
+function cloudflaredVersion() {
+    const r = spawnSync("cloudflared", ["--version"], { encoding: "utf8", timeout: 10_000 });
+    if (r.error || r.status !== 0)
+        return undefined;
+    return (r.stdout || r.stderr).trim().split("\n")[0];
+}
+/** Run one cloudflared command to completion, capturing its output (stderr carries the log lines). */
+function cloudflared(args) {
+    const r = spawnSync("cloudflared", args, { encoding: "utf8", timeout: 120_000, stdio: ["inherit", "pipe", "pipe"] });
+    return { ok: !r.error && r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+}
+/** Whether something already answers on the inspector port (so the tunnel has an origin). */
+function inspectorListening(port) {
+    return new Promise((resolve) => {
+        const req = http.get({ host: "127.0.0.1", port, path: "/api/meta?probe=1", timeout: 1_500 }, (res) => {
+            res.resume();
+            resolve(true);
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+/** A tunnel name from the project's display name or folder: "kraftwerk-agent-playground". */
+function defaultTunnelName(project) {
+    const base = (project.config.name ?? path.basename(project.root)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return `kraftwerk-${base || "inspector"}`;
+}
+/** The origin certificate `cloudflared tunnel login` writes; its presence means an authorized zone. */
+function originCertPath() {
+    return process.env.TUNNEL_ORIGIN_CERT || path.join(os.homedir(), ".cloudflared", "cert.pem");
+}
+/** Write public: and tunnel.name into kraftwerk.yml, keeping everything else (comments, an access block) as it is. */
+async function writeTunnelConfig(project, publicUrl, name) {
+    const configPath = project.configPath;
+    const doc = parseDocument(await readFile(configPath, "utf8"));
+    if (doc.errors.length > 0)
+        throw new Error(`${path.basename(configPath)}: ${doc.errors[0].message}`);
+    doc.set("public", publicUrl);
+    const tunnel = doc.get("tunnel");
+    if (tunnel && typeof tunnel === "object") {
+        doc.setIn(["tunnel", "name"], name);
+        doc.deleteIn(["tunnel", "enabled"]);
+    }
+    else {
+        doc.set("tunnel", { name });
+    }
+    await writeFile(configPath, doc.toString());
+    return configPath;
+}
+export function registerTunnelCommands(program) {
+    const tunnel = program
+        .command("tunnel")
+        .description("Cloudflare Tunnel to the inspector: run the configured one alone, or set one up");
+    tunnel
+        .command("run", { isDefault: true })
+        .description("Run the project's tunnel in the foreground (the inspector runs separately, e.g. `kraftwerk ui` elsewhere)")
+        .option("--port <port>", "Inspector port to route to (default: kraftwerk.yml `port`, else 1981)")
+        .action(async (opts) => {
+        const project = await resolveProject(process.cwd()).catch((err) => die(err.message, 2));
+        if (!tunnelFor(project)) {
+            die("tunnel is off — `kraftwerk tunnel setup <hostname>` creates one, or add `public:` and `tunnel:` to kraftwerk.yml (see kraftwerk doctor).");
+        }
+        const port = opts.port ? Number(opts.port) : (project.config.port ?? 1981);
+        if (!Number.isInteger(port) || port <= 0)
+            die("--port must be a port number", 2);
+        if (!(await inspectorListening(port))) {
+            console.log(chalk.yellow(`⚠ nothing answers on http://127.0.0.1:${port} yet — start \`kraftwerk ui\`; the tunnel serves errors until then.`));
+        }
+        const running = startTunnel(project, port);
+        if (!running)
+            process.exit(1);
+        for (const sig of ["SIGINT", "SIGTERM"])
+            process.once(sig, () => running.stop());
+        const outcome = await running.done;
+        process.exit(outcome === "failed" ? 1 : 0);
+    });
+    tunnel
+        .command("setup <hostname>")
+        .description("Create a locally-managed tunnel for this project and route the hostname to it (login, create, route dns, kraftwerk.yml)")
+        .option("--name <name>", "Tunnel name (default: kraftwerk-<project name>)")
+        .option("--overwrite-dns", "Replace an existing DNS record for the hostname")
+        .action(async (hostname, opts) => {
+        const host = parsePublic(hostname)?.hostname ?? die(`"${hostname}" is not a hostname — expected something like kw.example.com`, 2);
+        const project = await resolveProject(process.cwd()).catch((err) => die(err.message, 2));
+        if (!project.configPath)
+            die("no kraftwerk.yml here — `kraftwerk init` scaffolds one, then run setup again.", 2);
+        const name = opts.name ?? defaultTunnelName(project);
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name))
+            die(`"${name}" is not a plain tunnel name (letters, digits, ".", "_", "-")`, 2);
+        const version = cloudflaredVersion();
+        if (!version)
+            die("cloudflared not found — brew install cloudflared (or see developers.cloudflare.com), then run setup again.");
+        console.log(`${chalk.green("✔")} ${version}`);
+        // 1. Login: one authorized zone at a time, stored as cert.pem.
+        if (existsSync(originCertPath())) {
+            console.log(`${chalk.green("✔")} logged in to Cloudflare ${chalk.dim(`(${originCertPath()})`)}`);
+        }
+        else {
+            console.log(`${chalk.dim("↗")} cloudflared tunnel login — pick the zone that ${chalk.bold(host)} belongs to in the browser`);
+            const login = spawnSync("cloudflared", ["tunnel", "login"], { stdio: "inherit" });
+            if (login.error || login.status !== 0 || !existsSync(originCertPath()))
+                die("cloudflared tunnel login did not complete.");
+            console.log(`${chalk.green("✔")} logged in to Cloudflare`);
+        }
+        // 2. The tunnel: reuse one of that name, else create it.
+        const list = cloudflared(["tunnel", "list", "--output", "json", "--name", name]);
+        if (!list.ok)
+            die(`cloudflared tunnel list failed:\n${list.out}`);
+        let existing;
+        try {
+            existing = JSON.parse(list.out || "[]").find((t) => t.name === name);
+        }
+        catch {
+            die(`cloudflared tunnel list returned no JSON:\n${list.out}`);
+        }
+        let id = existing?.id;
+        if (existing) {
+            console.log(`${chalk.green("✔")} tunnel ${chalk.bold(name)} exists ${chalk.dim(id ?? "")}`);
+        }
+        else {
+            const created = cloudflared(["tunnel", "create", "--output", "json", name]);
+            if (!created.ok)
+                die(`cloudflared tunnel create failed:\n${created.out}`);
+            try {
+                id = JSON.parse(created.out).id;
+            }
+            catch {
+                // Not fatal: the route step addresses the tunnel by name.
+            }
+            console.log(`${chalk.green("✔")} created tunnel ${chalk.bold(name)} ${chalk.dim(id ?? "")}`);
+        }
+        // 3. DNS: a CNAME from the hostname to the tunnel. cloudflared can
+        // exit 0 after quietly appending the authorized zone to a hostname
+        // outside it — compare the record it reports with the one asked for.
+        const route = cloudflared(["tunnel", "route", "dns", ...(opts.overwriteDns ? ["--overwrite-dns"] : []), name, host]);
+        const added = /Added CNAME (\S+)/.exec(route.out)?.[1]?.replace(/\.$/, "").toLowerCase();
+        if (!route.ok) {
+            const exists = /already exists/i.test(route.out);
+            die(`cloudflared tunnel route dns failed:\n${route.out}` +
+                (exists && !opts.overwriteDns ? `\n\nA record for ${host} exists. If it should point at this tunnel, run setup again with --overwrite-dns.` : ""));
+        }
+        if (added && added !== host.toLowerCase()) {
+            die(`cloudflared routed ${chalk.bold(added)} instead of ${chalk.bold(host)}: the hostname is outside the zone you logged in to.\n` +
+                `Delete the stray CNAME ${added} in the Cloudflare dashboard, run \`cloudflared tunnel login\` for the right zone, then setup again.`);
+        }
+        console.log(`${chalk.green("✔")} ${host} → tunnel ${name}`);
+        // 4. kraftwerk.yml
+        const publicUrl = `https://${host}`;
+        const configPath = await writeTunnelConfig(project, publicUrl, name).catch((err) => die(err.message));
+        console.log(`${chalk.green("✔")} ${path.basename(configPath)}: public: ${publicUrl}, tunnel.name: ${name}`);
+        const port = project.config.port ?? 1981;
+        console.log(`\n${chalk.bold("Next:")} put a Cloudflare Access policy on ${host} — the UI has no login of its own.\n` +
+            `  Zero Trust → Access → Applications → Add an application → Self-hosted, domain ${host}: https://one.dash.cloudflare.com/\n` +
+            `  Then copy the team name and the application's Audience tag into kraftwerk.yml so the inspector verifies every login:\n` +
+            chalk.dim(`    tunnel:\n      name: ${name}\n      access:\n        team: <team>          # https://<team>.cloudflareaccess.com\n        aud: <audience tag>\n`) +
+            `\n\`kraftwerk ui\` now starts the tunnel with the inspector (port ${port}); \`kraftwerk tunnel\` runs it alone. \`kraftwerk doctor\` checks it.`);
+    });
+}

package/dist/cli/ui.js

@@ -4,7 +4,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import chalk from "chalk";
-import { absolutePath, resolveProject } from "../config.js";
+import { absolutePath, publicUrlFor, resolveProject } from "../config.js";
+import { startTunnel } from "./tunnel.js";
 import { selfCommand } from "../inspector/self-command.js";
 import { RESTART_EXIT_CODE, startInspector } from "../inspector/server.js";
 /**
@@ -49,7 +50,7 @@ function ensureBuilt() {
 }
 export async function runUi(cwd, opts) {
     if (process.env.KRAFTWERK_UI_SUPERVISED !== "1")
-        return superviseUi(opts);
+        return superviseUi(cwd, opts);
     const staticDir = ensureBuilt();
     const project = await resolveProject(cwd);
     const outputDir = opts.output ? absolutePath(opts.output, cwd) : project.outputDir;
@@ -58,6 +59,9 @@ export async function runUi(cwd, opts) {
     await startInspector({ outputDir, staticDir, port, projectRoot: project.root });
     console.log(`${chalk.green("✔")} Kraftwerk UI: ${chalk.cyan(`http://localhost:${port}`)} ` +
         chalk.dim(`(output: ${outputDir})`));
+    const publicUrl = publicUrlFor(project);
+    if (publicUrl)
+        console.log(`${chalk.green("✔")} Public URL: ${chalk.cyan(publicUrl)}`);
 }
 /**
  * Respawn loop around the real server. Spawns this same bin script via the
@@ -68,18 +72,23 @@ export async function runUi(cwd, opts) {
  * projects start` reports) takes the whole UI down; Ctrl-C signals the
  * foreground group and reaches both anyway.
  */
-async function superviseUi(opts) {
+async function superviseUi(cwd, opts) {
     const { cmd, args } = selfCommand([
         "ui",
         ...(opts.port ? ["--port", opts.port] : []),
         ...(opts.output ? ["--output", opts.output] : []),
     ]);
+    // The tunnel lives with the supervisor, not the server: a self-restart
+    // (new version) swaps the server process and the tunnel stays up.
+    const project = await resolveProject(cwd).catch(() => null);
+    const tunnel = project ? startTunnel(project, opts.port ? Number(opts.port) : (project.config.port ?? 1981)) : undefined;
     for (;;) {
         const child = spawn(cmd, args, {
             stdio: "inherit",
             env: { ...process.env, KRAFTWERK_UI_SUPERVISED: "1" },
         });
         const forward = (sig) => () => {
+            tunnel?.stop();
             child.kill(sig);
         };
         const handlers = { SIGTERM: forward("SIGTERM"), SIGINT: forward("SIGINT") };
@@ -91,6 +100,7 @@ async function superviseUi(opts) {
         process.off("SIGTERM", handlers.SIGTERM);
         process.off("SIGINT", handlers.SIGINT);
         if (result.code !== RESTART_EXIT_CODE) {
+            tunnel?.stop();
             // A signal-killed server is not a clean exit — say so in the exit code
             // (128 + signal, the shell convention) so callers can tell.
             if (result.signal)

package/dist/config.d.ts

@@ -30,6 +30,12 @@
  *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
  *   vibeables:                 # small apps built live in a chat, rendered in the inspector (absent = off, bare key = on)
  *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
+ *   public: https://kw.example.com   # hostname the inspector is reached at through a tunnel or reverse proxy
+ *   tunnel:                    # Cloudflare Tunnel run by `kraftwerk ui` (absent = off, bare key = on)
+ *     name: kraftwerk          # locally-managed tunnel (cloudflared tunnel create); absent: TUNNEL_TOKEN env, dashboard-managed
+ *     access:                  # verify the Cloudflare Access login on every request that arrives via `public`
+ *       team: acme             # Zero Trust team name (https://<team>.cloudflareaccess.com)
+ *       aud: 4714c135…         # Application Audience tag of the Access application
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -96,6 +102,47 @@ export interface VibeablesConfig {
 export declare const VIBEABLES_DEFAULT_ROOT = "kraftwerk-data/vibeables";
 /** Absolute vibeables root when the feature is on, undefined otherwise. */
 export declare function vibeablesRootFor(project: Project): string | undefined;
+/**
+ * Cloudflare Access in front of the public hostname. Access puts a login
+ * page on the hostname at Cloudflare's edge and hands the origin a signed
+ * JWT per request (Cf-Access-Jwt-Assertion). With this block the inspector
+ * verifies that token itself, so a removed or misconfigured Access policy
+ * fails closed instead of exposing the UI, which has no login of its own.
+ */
+export interface AccessConfig {
+    /** Zero Trust team name: the subdomain of https://<team>.cloudflareaccess.com */
+    team: string;
+    /** Application Audience (AUD) tag of the Access application, from its overview page. */
+    aud: string;
+}
+/**
+ * Cloudflare Tunnel: `kraftwerk ui` runs cloudflared next to the inspector
+ * so the loopback bind is reachable at `public` without an open port. The
+ * tunnel itself is created once with cloudflared (or in the Zero Trust
+ * dashboard); this block only says which one to run.
+ */
+export interface TunnelConfig {
+    /** false keeps the block but turns the feature off. Default: true. */
+    enabled?: boolean;
+    /**
+     * Name of a locally-managed tunnel (`cloudflared tunnel create <name>`,
+     * `cloudflared tunnel route dns <name> <public host>`); cloudflared routes
+     * everything to the inspector port. Absent: a dashboard-managed tunnel,
+     * whose token comes from the TUNNEL_TOKEN environment variable and whose
+     * route to http://localhost:<port> is configured in the dashboard.
+     */
+    name?: string;
+    /** Verify the Cloudflare Access token on every request that arrives via `public`. */
+    access?: AccessConfig;
+}
+/** The public hostname (lowercase, no port) when `public` is set, undefined otherwise. */
+export declare function publicHostFor(project: Project): string | undefined;
+/** The public origin ("https://kw.example.com") when `public` is set, undefined otherwise. */
+export declare function publicUrlFor(project: Project): string | undefined;
+/** The tunnel block when the feature is on, undefined otherwise. */
+export declare function tunnelFor(project: Project): TunnelConfig | undefined;
+/** "kw.example.com" or "https://kw.example.com[:port]" → its URL; undefined when it is neither. */
+export declare function parsePublic(value: string): URL | undefined;
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export declare function ignoreEntryFor(projectRoot: string, dir: string): string | undefined;
 /** True when .gitignore text already covers the entry (with or without a leading or trailing slash). */
@@ -136,6 +183,14 @@ export interface ProjectConfig {
     repos?: ReposConfig;
     /** Vibeables: apps built live in a chat. Absent = off. */
     vibeables?: VibeablesConfig;
+    /**
+     * Hostname the inspector is reached at through a tunnel or reverse proxy,
+     * e.g. "https://kw.example.com". The loopback bind then answers requests
+     * carrying that Host even without X-Forwarded-Host (cloudflared sends none).
+     */
+    public?: string;
+    /** Cloudflare Tunnel run alongside the inspector. Absent = off. */
+    tunnel?: TunnelConfig;
 }
 export interface Project {
     /** Absolute project root the CLI operates on. */

package/dist/config.js

@@ -34,6 +34,12 @@ import { parse } from "yaml";
  *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
  *   vibeables:                 # small apps built live in a chat, rendered in the inspector (absent = off, bare key = on)
  *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
+ *   public: https://kw.example.com   # hostname the inspector is reached at through a tunnel or reverse proxy
+ *   tunnel:                    # Cloudflare Tunnel run by `kraftwerk ui` (absent = off, bare key = on)
+ *     name: kraftwerk          # locally-managed tunnel (cloudflared tunnel create); absent: TUNNEL_TOKEN env, dashboard-managed
+ *     access:                  # verify the Cloudflare Access login on every request that arrives via `public`
+ *       team: acme             # Zero Trust team name (https://<team>.cloudflareaccess.com)
+ *       aud: 4714c135…         # Application Audience tag of the Access application
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -78,6 +84,34 @@ export function vibeablesRootFor(project) {
         return undefined;
     return path.resolve(project.root, v.root ?? VIBEABLES_DEFAULT_ROOT);
 }
+/** The public hostname (lowercase, no port) when `public` is set, undefined otherwise. */
+export function publicHostFor(project) {
+    return project.config.public ? parsePublic(project.config.public)?.hostname : undefined;
+}
+/** The public origin ("https://kw.example.com") when `public` is set, undefined otherwise. */
+export function publicUrlFor(project) {
+    return project.config.public ? parsePublic(project.config.public)?.origin : undefined;
+}
+/** The tunnel block when the feature is on, undefined otherwise. */
+export function tunnelFor(project) {
+    const t = project.config.tunnel;
+    if (!t || t.enabled === false)
+        return undefined;
+    return t;
+}
+/** "kw.example.com" or "https://kw.example.com[:port]" → its URL; undefined when it is neither. */
+export function parsePublic(value) {
+    const text = value.trim();
+    try {
+        const url = new URL(/^https?:\/\//i.test(text) ? text : `https://${text}`);
+        if (!url.hostname || url.pathname !== "/" || url.search || url.hash || url.username)
+            return undefined;
+        return url;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export function ignoreEntryFor(projectRoot, dir) {
     const rel = path.relative(projectRoot, path.resolve(projectRoot, dir)).split(path.sep).join("/");
@@ -153,7 +187,7 @@ export async function resolveProject(cwd) {
     const root = gitFallback ?? start;
     return { root, config: {}, outputDir: path.join(root, "output") };
 }
-const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables"];
+const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "public", "tunnel"];
 async function loadConfig(configPath) {
     let raw;
     try {
@@ -204,12 +238,64 @@ async function loadConfig(configPath) {
                 config[key] = {};
             validateRootBlock(configPath, "vibeables", config[key]);
         }
+        else if (key === "public") {
+            if (typeof config[key] !== "string" || !parsePublic(config[key])) {
+                throw new Error(`${path.basename(configPath)}: public must be a hostname or https URL like "https://kw.example.com"`);
+            }
+        }
+        else if (key === "tunnel") {
+            if (config[key] === null)
+                config[key] = {};
+            validateTunnel(configPath, config[key]);
+        }
         else if (typeof config[key] !== "string") {
             throw new Error(`${path.basename(configPath)}: ${key} must be a string`);
         }
     }
+    const tunnel = config.tunnel;
+    if (tunnel && tunnel.enabled !== false && !config.public) {
+        throw new Error(`${path.basename(configPath)}: tunnel needs public: the hostname the tunnel routes to`);
+    }
     return config;
 }
+/** tunnel: { enabled?, name?, access?: { team, aud } } */
+function validateTunnel(configPath, value) {
+    const file = path.basename(configPath);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${file}: tunnel must be a mapping (enabled, name, access)`);
+    }
+    const t = value;
+    for (const key of Object.keys(t)) {
+        if (!["enabled", "name", "access"].includes(key)) {
+            throw new Error(`${file}: tunnel.${key} is unknown (allowed: enabled, name, access)`);
+        }
+    }
+    if (t.enabled !== undefined && typeof t.enabled !== "boolean") {
+        throw new Error(`${file}: tunnel.enabled must be true or false`);
+    }
+    // The name is handed to cloudflared as a positional argument.
+    if (t.name !== undefined && (typeof t.name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(t.name))) {
+        throw new Error(`${file}: tunnel.name must be a plain tunnel name (letters, digits, ".", "_", "-")`);
+    }
+    if (t.access !== undefined) {
+        if (typeof t.access !== "object" || t.access === null || Array.isArray(t.access)) {
+            throw new Error(`${file}: tunnel.access must be a mapping (team, aud)`);
+        }
+        const a = t.access;
+        for (const key of Object.keys(a)) {
+            if (!["team", "aud"].includes(key)) {
+                throw new Error(`${file}: tunnel.access.${key} is unknown (allowed: team, aud)`);
+            }
+        }
+        // The team becomes a hostname (<team>.cloudflareaccess.com).
+        if (typeof a.team !== "string" || !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/i.test(a.team)) {
+            throw new Error(`${file}: tunnel.access.team must be the Zero Trust team name (the subdomain of cloudflareaccess.com)`);
+        }
+        if (typeof a.aud !== "string" || !/^[a-f0-9]{64}$/i.test(a.aud)) {
+            throw new Error(`${file}: tunnel.access.aud must be the 64-character Application Audience tag`);
+        }
+    }
+}
 function validateSwitcher(configPath, value) {
     const file = path.basename(configPath);
     if (!Array.isArray(value)) {

package/dist/inspector/access.d.ts

@@ -0,0 +1,32 @@
+import type { AccessConfig } from "../config.js";
+/**
+ * Cloudflare Access token verification for requests that arrive via the
+ * public hostname. Access authenticates the browser at Cloudflare's edge and
+ * forwards a signed JWT per request in Cf-Access-Jwt-Assertion; the signing
+ * keys are public at https://<team>.cloudflareaccess.com/cdn-cgi/access/certs.
+ * Verifying the token here means the inspector, which has no login of its
+ * own, does not have to trust that the policy in the dashboard still exists.
+ *
+ * Dependency-free: RS256 over node:crypto. Keys are cached per team and
+ * refetched when a token names an unknown key id (rotation), at most once
+ * per REFETCH_INTERVAL so a flood of bogus tokens cannot hammer Cloudflare.
+ */
+export declare const ACCESS_HEADER = "cf-access-jwt-assertion";
+export type AccessResult = {
+    ok: true;
+    email?: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Team domain Access issues tokens for. Tests override the certs location. */
+export declare function teamDomain(team: string): string;
+/**
+ * Verify one Access token against the team's keys, the application's
+ * audience and the clock. Returns a reason instead of throwing so the
+ * caller can answer 401 with it; a certs fetch failure is a reason too
+ * (fail closed).
+ */
+export declare function verifyAccessToken(token: string, access: AccessConfig): Promise<AccessResult>;
+/** Forget cached keys (tests). */
+export declare function resetAccessKeys(): void;

package/dist/inspector/access.js

@@ -0,0 +1,121 @@
+import { createPublicKey, verify as verifySignature } from "node:crypto";
+/**
+ * Cloudflare Access token verification for requests that arrive via the
+ * public hostname. Access authenticates the browser at Cloudflare's edge and
+ * forwards a signed JWT per request in Cf-Access-Jwt-Assertion; the signing
+ * keys are public at https://<team>.cloudflareaccess.com/cdn-cgi/access/certs.
+ * Verifying the token here means the inspector, which has no login of its
+ * own, does not have to trust that the policy in the dashboard still exists.
+ *
+ * Dependency-free: RS256 over node:crypto. Keys are cached per team and
+ * refetched when a token names an unknown key id (rotation), at most once
+ * per REFETCH_INTERVAL so a flood of bogus tokens cannot hammer Cloudflare.
+ */
+export const ACCESS_HEADER = "cf-access-jwt-assertion";
+const KEY_TTL = 60 * 60 * 1000;
+const REFETCH_INTERVAL = 10 * 1000;
+const FETCH_TIMEOUT = 5_000;
+const cache = new Map();
+/** Team domain Access issues tokens for. Tests override the certs location. */
+export function teamDomain(team) {
+    return `https://${team}.cloudflareaccess.com`;
+}
+function certsUrl(team) {
+    return process.env.KRAFTWERK_ACCESS_CERTS_URL || `${teamDomain(team)}/cdn-cgi/access/certs`;
+}
+async function fetchKeys(team) {
+    const res = await fetch(certsUrl(team), { signal: AbortSignal.timeout(FETCH_TIMEOUT) });
+    if (!res.ok)
+        throw new Error(`certs endpoint answered ${res.status}`);
+    const body = (await res.json());
+    const keys = new Map();
+    for (const jwk of body.keys ?? []) {
+        if (typeof jwk.kid !== "string" || jwk.kty !== "RSA")
+            continue;
+        try {
+            keys.set(jwk.kid, createPublicKey({ key: jwk, format: "jwk" }));
+        }
+        catch {
+            // One malformed key must not take the rest down.
+        }
+    }
+    return keys;
+}
+async function keyFor(team, kid) {
+    const now = Date.now();
+    let entry = cache.get(team);
+    if (!entry || now - entry.fetchedAt > KEY_TTL) {
+        entry = { keys: await fetchKeys(team), fetchedAt: now, missedAt: 0 };
+        cache.set(team, entry);
+    }
+    const hit = entry.keys.get(kid);
+    if (hit)
+        return hit;
+    if (now - entry.missedAt < REFETCH_INTERVAL)
+        return undefined;
+    entry.missedAt = now;
+    entry.keys = await fetchKeys(team);
+    entry.fetchedAt = now;
+    return entry.keys.get(kid);
+}
+function decodeSegment(seg) {
+    try {
+        const parsed = JSON.parse(Buffer.from(seg, "base64url").toString("utf8"));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Verify one Access token against the team's keys, the application's
+ * audience and the clock. Returns a reason instead of throwing so the
+ * caller can answer 401 with it; a certs fetch failure is a reason too
+ * (fail closed).
+ */
+export async function verifyAccessToken(token, access) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return { ok: false, reason: "malformed token" };
+    const [h, p, s] = parts;
+    const header = decodeSegment(h);
+    const payload = decodeSegment(p);
+    if (!header || !payload)
+        return { ok: false, reason: "malformed token" };
+    if (header.alg !== "RS256" || typeof header.kid !== "string")
+        return { ok: false, reason: "unsupported token" };
+    let key;
+    try {
+        key = await keyFor(access.team, header.kid);
+    }
+    catch (err) {
+        return { ok: false, reason: `cannot fetch Access keys: ${err.message}` };
+    }
+    if (!key)
+        return { ok: false, reason: "unknown signing key" };
+    let valid = false;
+    try {
+        valid = verifySignature("RSA-SHA256", Buffer.from(`${h}.${p}`), key, Buffer.from(s, "base64url"));
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        return { ok: false, reason: "bad signature" };
+    if (payload.iss !== teamDomain(access.team))
+        return { ok: false, reason: "wrong issuer" };
+    const aud = payload.aud;
+    const audOk = Array.isArray(aud) ? aud.includes(access.aud) : aud === access.aud;
+    if (!audOk)
+        return { ok: false, reason: "wrong audience" };
+    const now = Math.floor(Date.now() / 1000);
+    if (typeof payload.exp !== "number" || payload.exp <= now)
+        return { ok: false, reason: "token expired" };
+    if (typeof payload.nbf === "number" && payload.nbf > now)
+        return { ok: false, reason: "token not yet valid" };
+    return { ok: true, email: typeof payload.email === "string" ? payload.email : undefined };
+}
+/** Forget cached keys (tests). */
+export function resetAccessKeys() {
+    cache.clear();
+}

package/dist/inspector/server.js

@@ -3,7 +3,8 @@ import http from "node:http";
 import path from "node:path";
 import { attachmentPath, saveAttachment } from "./chat/store.js";
 import { setOutputDir, setProjectRoot, getOutputDir, getProjectRoot } from "./context.js";
-import { resolveProject } from "../config.js";
+import { publicHostFor, publicUrlFor, resolveProject, tunnelFor } from "../config.js";
+import { ACCESS_HEADER, verifyAccessToken } from "./access.js";
 import { listRuns, getRun, readRunFile, deleteRun } from "./runs.js";
 import { canSelfUpdate, startUpdate, updateStatus } from "./update.js";
 import { listWorkflows, getWorkflow } from "./workflows.js";
@@ -99,6 +100,16 @@ const IN_CONTAINER = existsSync("/.dockerenv") || existsSync("/run/.containerenv
 const INSPECTOR_HOST = process.env.KRAFTWERK_UI_HOST || (IN_CONTAINER ? "0.0.0.0" : "127.0.0.1");
 const LOOPBACK_NAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
 const LOOPBACK_BIND = LOOPBACK_NAMES.has(INSPECTOR_HOST);
+/**
+ * The hostname from kraftwerk.yml `public`, when set: the name a tunnel or
+ * reverse proxy delivers as Host. A Cloudflare Tunnel forwards the
+ * browser's Host untouched and sets no X-Forwarded-Host, so without this
+ * the loopback bind would refuse every request that came through it. A
+ * rebinding page cannot exploit it: the name is one the operator owns.
+ */
+let publicHost = "";
+/** Access verification for requests arriving via the public hostname (kraftwerk.yml `tunnel.access`). */
+let access;
 /**
  * Whether the Host header names this server. A loopback bind alone does not
  * keep other sites out: a page on evil.example can re-point that name at
@@ -123,7 +134,32 @@ function hostAllowed(req) {
     if (!host)
         return true;
     const name = hostnameOf(host);
-    return LOOPBACK_NAMES.has(name) || name.endsWith(".localhost");
+    return LOOPBACK_NAMES.has(name) || name.endsWith(".localhost") || (!!publicHost && name === publicHost);
+}
+/** Whether the browser addressed the public hostname (directly or, via a proxy, in X-Forwarded-Host). */
+function viaPublicHost(req) {
+    if (!publicHost)
+        return false;
+    const host = forwardedHost(req) || req.headers.host;
+    return !!host && hostnameOf(host) === publicHost;
+}
+/**
+ * The Access gate: a request that arrived via the public hostname must
+ * carry a valid Cloudflare Access token when `tunnel.access` is configured.
+ * Requests addressed to a loopback name are the operator's own browser on
+ * this machine and pass; bound to loopback, only the tunnel (or a local
+ * proxy) can deliver the public name in the first place. Returns the reason
+ * to refuse, or undefined to proceed.
+ */
+async function accessRefusal(req) {
+    if (!access || !viaPublicHost(req))
+        return undefined;
+    const raw = req.headers[ACCESS_HEADER];
+    const token = Array.isArray(raw) ? raw[0] : raw;
+    if (!token)
+        return "Cloudflare Access token missing";
+    const result = await verifyAccessToken(token, access);
+    return result.ok ? undefined : `Cloudflare Access token refused: ${result.reason}`;
 }
 /** First X-Forwarded-Host value, or undefined when no proxy set one. */
 function forwardedHost(req) {
@@ -348,6 +384,7 @@ async function handleApi(req, res, url) {
             git: (project?.config.git && project.config.git.enabled !== false) === true,
             repos: (project?.config.repos && project.config.repos.enabled !== false) === true,
             vibeables: (project?.config.vibeables && project.config.vibeables.enabled !== false) === true,
+            publicUrl: (project && publicUrlFor(project)) ?? "",
             switcher,
         });
     }
@@ -1181,10 +1218,14 @@ async function serveStatic(res, staticDir, pathname) {
     res.end(buf);
 }
 /** Start the server; resolves once it listens. Runs until the process ends. */
-export function startInspector(opts) {
+export async function startInspector(opts) {
     setOutputDir(opts.outputDir);
     if (opts.projectRoot)
         setProjectRoot(opts.projectRoot);
+    // Read once: like the port, the public hostname takes effect on restart.
+    const project = await resolveProject(getProjectRoot()).catch(() => null);
+    publicHost = (project && publicHostFor(project)) ?? "";
+    access = project ? tunnelFor(project)?.access : undefined;
     startRoutineScheduler();
     startGitSync();
     // Chat agent subprocesses must die with the server — signals bypass
@@ -1211,6 +1252,9 @@ export function startInspector(opts) {
             const url = new URL(req.url ?? "/", "http://localhost");
             if (!hostAllowed(req))
                 return json(res, { error: "unexpected Host header" }, 421);
+            const refusal = await accessRefusal(req);
+            if (refusal)
+                return json(res, { error: refusal }, 401);
             if (url.pathname.startsWith("/api/"))
                 await handleApi(req, res, url);
             // /vibeables/<slug>/… is an app's own files, served for the preview pane.
@@ -1227,7 +1271,7 @@ export function startInspector(opts) {
     server.on("upgrade", (req, socket, head) => {
         if (!hostAllowed(req))
             return void socket.destroy();
-        proxyUpgrade(req, socket, head);
+        accessRefusal(req).then((refusal) => (refusal ? socket.destroy() : proxyUpgrade(req, socket, head)), () => socket.destroy());
     });
     return new Promise((resolve, reject) => {
         server.once("error", reject);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netnodeag/kraftwerk",
-  "version": "0.46.2",
+  "version": "0.47.0",
   "description": "Open-source agentic workspace for teams — where people and AI agents get work done together: agents (Claude Code, Codex, Pi), skills, shared knowledge, repeatable workflows, and deterministic verification",
   "keywords": [
     "agents",

package/schema/kraftwerk.schema.json

@@ -14,6 +14,11 @@
       "type": "string",
       "description": "Emoji used as the inspector favicon (browser-tab icon), e.g. \"⚡\""
     },
+    "color": {
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+      "description": "Accent colour for this workspace in the switcher and the inspector, e.g. \"#c2410c\". Default: derived from the project root"
+    },
     "port": {
       "type": "integer",
       "minimum": 1,
@@ -69,7 +74,10 @@
       }
     },
     "git": {
-      "type": ["object", "null"],
+      "type": [
+        "object",
+        "null"
+      ],
       "additionalProperties": false,
       "description": "Git sync for the workspace: commit and push knowledge, agents, skills and workflows from the inspector. Absent = feature off, a bare `git:` = on with defaults.",
       "properties": {
@@ -100,7 +108,10 @@
       }
     },
     "repos": {
-      "type": ["object", "null"],
+      "type": [
+        "object",
+        "null"
+      ],
       "additionalProperties": false,
       "description": "Repositories: git clones the agents work on, kept under one root inside the project. Absent = feature off, a bare `repos:` = on with defaults.",
       "properties": {
@@ -113,6 +124,68 @@
           "description": "Where clones land, relative to the project root. Should be git-ignored. Default: repos"
         }
       }
+    },
+    "vibeables": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": false,
+      "description": "Vibeables: small apps built live in a chat with a preview pane, one folder each under the root, part of the workspace. Absent = feature off, a bare `vibeables:` = on with defaults.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Turn the feature off while keeping the config. Default: true when this block exists"
+        },
+        "root": {
+          "type": "string",
+          "description": "Where the apps live, relative to the project root. Default: kraftwerk-data/vibeables"
+        }
+      }
+    },
+    "public": {
+      "type": "string",
+      "description": "Hostname the inspector is reached at through a tunnel or reverse proxy, e.g. \"https://kw.example.com\". The loopback bind then answers requests carrying that Host even without X-Forwarded-Host (cloudflared sends none)."
+    },
+    "tunnel": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": false,
+      "description": "Cloudflare Tunnel run by `kraftwerk ui` next to the inspector, so the loopback bind is reachable at `public` without an open port. Needs `public`. Absent = feature off, a bare `tunnel:` = on with defaults.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Turn the feature off while keeping the config. Default: true when this block exists"
+        },
+        "name": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
+          "description": "Name of a locally-managed tunnel (`cloudflared tunnel create <name>` + `cloudflared tunnel route dns <name> <public host>`); cloudflared routes everything to the inspector port. Absent: a dashboard-managed tunnel whose token is read from the TUNNEL_TOKEN environment variable"
+        },
+        "access": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "team",
+            "aud"
+          ],
+          "description": "Verify the Cloudflare Access token (Cf-Access-Jwt-Assertion) on every request that arrives via `public`. Recommended: the UI has no login of its own, and with this a removed Access policy fails closed",
+          "properties": {
+            "team": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$",
+              "description": "Zero Trust team name: the subdomain of https://<team>.cloudflareaccess.com"
+            },
+            "aud": {
+              "type": "string",
+              "pattern": "^[a-fA-F0-9]{64}$",
+              "description": "Application Audience (AUD) tag of the Access application, shown on its overview page in the Zero Trust dashboard"
+            }
+          }
+        }
+      }
     }
   }
 }