@kybernesis/create 0.4.0 → 0.5.1

package/dist/doctor.js

@@ -90,24 +90,39 @@ export async function doctor() {
         add("warn", "KYBERNESIS_ISSUER not set", "agent is not control-plane governed");
     }
     // ── slack ──────────────────────────────────────────────────────────────
-    if (env.SLACK_CONNECTOR_UID)
-        add("pass", `Slack connector uid: ${env.SLACK_CONNECTOR_UID}`, "verify trigger path /eve/v1/slack (vercel connect list)");
-    else
-        add("warn", "SLACK_CONNECTOR_UID not set", "vercel connect create slack --triggers");
+    // Only relevant when the agent actually has a Slack channel — a client on
+    // iMessage or Telegram should never be told to create a Slack connector.
+    const hasSlackChannel = existsSync(join(cwd, "agent/channels/slack.ts"));
+    if (hasSlackChannel) {
+        if (env.SLACK_CONNECTOR_UID)
+            add("pass", `Slack connector uid: ${env.SLACK_CONNECTOR_UID}`, "verify trigger path /eve/v1/slack (vercel connect list)");
+        else if (env.SLACK_BOT_TOKEN)
+            add("pass", "Slack via portable credentials (SLACK_BOT_TOKEN)");
+        else
+            add("warn", "Slack channel present but no credentials", "SLACK_CONNECTOR_UID (Vercel) or SLACK_BOT_TOKEN (portable)");
+    }
     // ── engineer layer (optional — checked only when installed) ────────────
     const hasEngineer = Boolean(deps["@kybernesis/engineer"]) || existsSync(join(cwd, "agent/extensions/engineer.ts"));
     if (hasEngineer) {
         add("pass", `@kybernesis/engineer ${deps["@kybernesis/engineer"] ?? "(extension file present)"}`);
-        if (existsSync(join(cwd, "agent/sandbox/sandbox.ts")))
-            add("pass", "workshop sandbox file present");
-        else
-            add("fail", "agent/sandbox/sandbox.ts missing", "eve add @kybernesis/engineer --overwrite writes it");
-        if (env.BLOB_READ_WRITE_TOKEN)
-            add("pass", "file delivery configured (BLOB_READ_WRITE_TOKEN)");
-        else
-            add("warn", "BLOB_READ_WRITE_TOKEN not set — deliver tool will fail", "vercel blob create-store <name>-deliverables --access public --yes");
+        // The workshop may sit on the root OR on the engineer subagent (the
+        // scoped pattern). Either is valid; neither is not.
+        const rootSandbox = existsSync(join(cwd, "agent/sandbox/sandbox.ts"));
+        const builderSandbox = existsSync(join(cwd, "agent/subagents/builder/sandbox/sandbox.ts"));
+        if (rootSandbox || builderSandbox) {
+            add("pass", `workshop sandbox present (${builderSandbox ? "engineer subagent" : "root agent"})`);
+        }
+        else {
+            add("fail", "no workshop sandbox", "the engineer layer needs one — on the root or on agent/subagents/builder/");
+        }
         const vercelConn = join(cwd, "agent/connections/vercel.ts");
-        if (existsSync(vercelConn)) {
+        const selfHostedAgent = Boolean(deps["@kybernesis/exe"]) ||
+            (existsSync(join(cwd, "agent/subagents/builder/sandbox/sandbox.ts")) &&
+                readFileSync(join(cwd, "agent/subagents/builder/sandbox/sandbox.ts"), "utf8").includes("docker("));
+        if (selfHostedAgent && !existsSync(vercelConn)) {
+            add("pass", "no Vercel MCP connection (self-hosted)", "public deploys need the CLIENT's own Vercel token — Vercel Connect does not work off-Vercel");
+        }
+        else if (existsSync(vercelConn)) {
             const src = readFileSync(vercelConn, "utf8");
             const uid = /connect\(\s*"([^"]+)"/.exec(src)?.[1];
             if (uid && uid.includes("/"))
@@ -118,10 +133,12 @@ export async function doctor() {
         else {
             add("warn", "agent/connections/vercel.ts missing — no preview deploys/link-back", "eve add connection/vercel, then vercel connect create + attach");
         }
-        if (env.VERCEL_OIDC_TOKEN || env.VERCEL_TOKEN)
-            add("pass", "Vercel credentials for local hosted sandboxes");
-        else
-            add("warn", "no VERCEL_OIDC_TOKEN — local sandbox/eval runs cannot reach Vercel Sandbox", "vercel link && vercel env pull");
+        if (!selfHostedAgent) {
+            if (env.VERCEL_OIDC_TOKEN || env.VERCEL_TOKEN)
+                add("pass", "Vercel credentials for local hosted sandboxes");
+            else
+                add("warn", "no VERCEL_OIDC_TOKEN — local sandbox/eval runs cannot reach Vercel Sandbox", "vercel link && vercel env pull");
+        }
     }
     // ── dispatch edges (agent-to-agent — checked only when present) ────────
     const subagentsDir = join(cwd, "agent/subagents");
@@ -168,6 +185,88 @@ export async function doctor() {
             add("warn", "@kybernesis/dispatch installed but no edges or dispatch channel found", "see the connect-agents skill");
         }
     }
+    // ── self-hosted agents (host !== Vercel) ───────────────────────────────
+    // Every check here cost a real debugging session on the first exe.dev
+    // deployment. None of them are theoretical.
+    const selfHosted = Boolean(deps["@kybernesis/exe"]) ||
+        existsSync(join(cwd, "agent/sandbox/sandbox.ts")) &&
+            readFileSync(join(cwd, "agent/sandbox/sandbox.ts"), "utf8").includes("docker(");
+    if (selfHosted) {
+        // Vercel Connect needs Vercel OIDC — it CANNOT work off-Vercel, for Slack,
+        // the Vercel MCP connection, or anything else. Every such connection has to
+        // become a static credential the client issues.
+        const connectUsers = [];
+        for (const dir of ["agent/channels", "agent/connections"]) {
+            const full = join(cwd, dir);
+            if (!existsSync(full))
+                continue;
+            for (const f of readdirSync(full)) {
+                const file = join(full, f);
+                if (!f.endsWith(".ts"))
+                    continue;
+                if (readFileSync(file, "utf8").includes("@vercel/connect"))
+                    connectUsers.push(`${dir}/${f}`);
+            }
+        }
+        if (connectUsers.length) {
+            add("fail", `Vercel Connect used off-Vercel: ${connectUsers.join(", ")}`, "Connect authenticates via Vercel OIDC, which does not exist on this host — the agent will fail to boot. Switch to portable/static credentials");
+        }
+        else {
+            add("pass", "no Vercel Connect dependencies (correct for a self-hosted agent)");
+        }
+        // eve start does not read .env.local the way eve dev does.
+        add("warn", "self-hosted: export .env.local into the server process", "eve start does NOT read it; use the supervision script from @kybernesis/exe (scripts/eve-server.sh)");
+        // Prewarm runs in the eve CLI, not the built server.
+        add("warn", "self-hosted: start via `npx eve start`, not `node .output/server/index.mjs`", "sandbox templates are prewarmed by the CLI; starting the server directly skips prewarm and every sandbox tool fails with SandboxTemplateNotProvisionedError");
+        // The exe VM sandbox backend needs a credential that cannot be scoped.
+        // Surface the blast radius here, where it is still cheap to change course.
+        const sandboxFile = join(cwd, "agent/sandbox/sandbox.ts");
+        const usesExeSandbox = existsSync(sandboxFile) && readFileSync(sandboxFile, "utf8").includes("exeSandbox(");
+        if (usesExeSandbox) {
+            const src = readFileSync(sandboxFile, "utf8");
+            if (src.includes("allowSharedAccount: true")) {
+                add("warn", "exeSandbox runs with allowSharedAccount: true", "the sandbox SSH key grants shell to EVERY VM on the exe.dev account — only keep this if the client has explicitly accepted that blast radius; otherwise give the agent its own account");
+            }
+            else {
+                add("pass", "exeSandbox enforces a dedicated exe.dev account");
+            }
+            if (!process.env.EXE_SANDBOX_SSH_KEY && !process.env.EXE_SANDBOX_SSH_KEY_PATH) {
+                add("fail", "exeSandbox has no SSH key (EXE_SANDBOX_SSH_KEY / EXE_SANDBOX_SSH_KEY_PATH)", "it must be a FULL-PERMISSION account key: a key registered through an API token inherits that token's command scope and cannot open a shell at all");
+            }
+            if (!process.env.EXE_API_TOKEN) {
+                add("fail", "exeSandbox has no EXE_API_TOKEN for VM lifecycle", "mint a narrow one: ssh exe.dev \"ssh-key generate-api-key --label=<agent>-sandbox --cmds='ls,new,rm,cp' --exp=7d\"");
+            }
+        }
+    }
+    // ── engineer subagent (build capability scoped to a subagent) ──────────
+    const builderDir = join(cwd, "agent/subagents/builder");
+    if (existsSync(builderDir)) {
+        // Subagents own their sandbox — they do NOT inherit the root's. Without one
+        // the builder gets a bare template and every screenshot fails with
+        // "Cannot find module 'playwright'" while the root's template is fine.
+        if (existsSync(join(builderDir, "sandbox/sandbox.ts"))) {
+            add("pass", "engineer subagent has its own workshop sandbox");
+        }
+        else {
+            add("fail", "engineer subagent has NO sandbox of its own", "subagents do not inherit the root sandbox — add agent/subagents/builder/sandbox/sandbox.ts or the vision loop cannot run");
+        }
+        if (existsSync(join(builderDir, "extensions/engineer.ts"))) {
+            add("pass", "engineer mounted locally on the subagent (root keeps no shell)");
+        }
+        else {
+            add("warn", "engineer extension not mounted on the subagent", "agent/subagents/builder/extensions/engineer.ts");
+        }
+        // Delivery: either storage works, or the agent cannot hand over artifacts.
+        if (env.BLOB_READ_WRITE_TOKEN) {
+            add("pass", "file delivery via Vercel Blob");
+        }
+        else if (env.DELIVER_DIR && env.DELIVER_BASE_URL) {
+            add("pass", `file delivery via host directory (${env.DELIVER_DIR})`);
+        }
+        else {
+            add("warn", "file delivery not configured — the agent cannot hand over artifacts", "set BLOB_READ_WRITE_TOKEN (the CLIENT's blob store) or DELIVER_DIR + DELIVER_BASE_URL");
+        }
+    }
     // ── eve discovery + local port ─────────────────────────────────────────
     const info = capture("npx", ["eve", "info"], cwd);
     if (info === null)

package/dist/init.js

@@ -1,7 +1,7 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { DEFAULT_ISSUER, EVE_VERSION, REGISTRY_URL, ask, bold, closePrompts, dim, green, run, slug, yellow, } from "./util.js";
-import { CHANNEL_KINDS, channelPlan, envExample, evalFileTs, evalScript, hostAgentTs, hostSteps, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
+import { CHANNEL_KINDS, channelPlan, engineerPlan, envExample, evalFileTs, evalScript, hostAgentTs, hostSteps, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
 import { suiteDir } from "./skills.js";
 /**
  * The always-installed core. Everything else — channels, subagents, engineer,
@@ -9,11 +9,11 @@ import { suiteDir } from "./skills.js";
  * AND undoes real setup work (an Arcana workspace + scoped key per subagent).
  */
 const CORE_ITEMS = ["enterprise", "arcana", "evals"];
-const ENGINEER_OFFICIAL_ITEMS = [
-    "extension/agent-browser",
-    "extension/github-tools",
-    "connection/vercel",
-];
+// Official eve-registry limbs installed with the engineer subagent.
+// connection/vercel is Vercel-Connect-backed, so it is VERCEL-HOST ONLY: on a
+// self-hosted agent it cannot get an OIDC token and the agent fails to boot.
+const ENGINEER_ITEMS_ALL = ["extension/agent-browser", "extension/github-tools"];
+const ENGINEER_ITEMS_VERCEL = ["connection/vercel"];
 const DEFAULT_MODEL = "anthropic/claude-sonnet-5";
 export async function init(rawName, options = {}) {
     const engineer = options.engineer === true;
@@ -70,10 +70,12 @@ export async function init(rawName, options = {}) {
     for (const item of plan.registryItems) {
         run("npx", ["eve", "add", item, "--overwrite"], { cwd: dir, allowFail: true });
     }
-    if (engineer) {
-        console.log(bold("\n2c   Engineer layer: workshop sandbox + vision dev loop …"));
-        run("npx", ["eve", "add", "@kybernesis/engineer", "--overwrite"], { cwd: dir });
-        for (const item of ENGINEER_OFFICIAL_ITEMS) {
+    const engPlan = engineer ? engineerPlan(host, DEFAULT_MODEL) : null;
+    if (engPlan) {
+        console.log(bold("\n2c   Engineer subagent: workshop sandbox + vision dev loop …"));
+        run("npm", ["install", ...engPlan.deps, "--no-audit", "--no-fund"], { cwd: dir, allowFail: true });
+        const engItems = [...ENGINEER_ITEMS_ALL, ...(host === "vercel" ? ENGINEER_ITEMS_VERCEL : [])];
+        for (const item of engItems) {
             const ok = run("npx", ["eve", "add", item, "--overwrite"], { cwd: dir, allowFail: true });
             if (!ok)
                 console.log(yellow(`  ! ${item} did not install cleanly — re-run: npx eve add ${item}`));
@@ -121,6 +123,13 @@ export async function init(rawName, options = {}) {
             }
         }
     }
+    if (engPlan) {
+        for (const file of engPlan.files) {
+            const full = join(dir, file.path);
+            mkdirSync(join(full, ".."), { recursive: true });
+            writeFileSync(full, file.content);
+        }
+    }
     console.log(bold("\n5/6  Env template + hermetic eval script …"));
     writeFileSync(join(dir, ".env.example"), envExample(name, depts, issuer, plan.env));
     const pkgPath = join(dir, "package.json");
@@ -139,13 +148,14 @@ export async function init(rawName, options = {}) {
         "self-testing (evals)",
         channel === "none" ? null : `${channel} channel`,
         host === "exe" ? "exe.dev host" : null,
-        engineer ? "engineer (workshop + vision loop)" : null,
+        engineer ? "engineer subagent (workshop + vision loop)" : null,
         depts.length ? `${depts.length} dept subagent(s)` : null,
     ].filter(Boolean);
     const steps = [
         `Arcana: create workspaces (${name}-company, ${name}-eval${depts.map((d) => `, ${name}-${d}`).join("")}) + scoped kb_ keys; fill .env.local from .env.example`,
         ...hostSteps(host, name),
         ...plan.steps,
+        ...(engPlan?.steps ?? []),
         `Control plane: register agent "${name}" at ${issuer}/agents + grant the pilot cohort`,
         `npm run eval → green → deploy → live smoke + the revoke demo`,
     ];

package/dist/templates.d.ts

@@ -28,3 +28,12 @@ export declare function channelPlan(kind: ChannelKind, name: string, host: HostK
 export type HostKind = "vercel" | "exe";
 export declare function hostAgentTs(host: HostKind, model: string): string;
 export declare function hostSteps(host: HostKind, name: string): string[];
+export interface EngineerPlan {
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    deps: string[];
+    steps: string[];
+}
+export declare function engineerPlan(host: HostKind, model: string): EngineerPlan;

package/dist/templates.js

@@ -334,3 +334,176 @@ export function hostSteps(host, name) {
         `npx eve deploy`,
     ];
 }
+/** The workshop sandbox, per host. Same recipe; different backend. */
+function workshopSandbox(host) {
+    if (host === "exe") {
+        return `import { defineSandbox } from "eve/sandbox";
+import { docker } from "eve/sandbox/docker";
+
+/**
+ * The engineer workshop, self-hosted: pnpm + Playwright + Chromium baked into
+ * the TEMPLATE so warm sessions run render→screenshot→vision in seconds.
+ *
+ * Docker rather than vercel(): the hosted backend needs Vercel OIDC, which does
+ * not exist off-Vercel.
+ *
+ * HOST PREREQUISITE: some images ship Docker disabled (exe.dev's exeuntu runs
+ * \`systemctl disable docker.service\`). Run \`sudo systemctl enable --now docker\`
+ * or every build fails with SandboxTemplateNotProvisionedError.
+ *
+ * NOTE: Docker sessions do not enforce a domain allowlist the way the hosted
+ * backend does. Egress control is the HOST's responsibility here — a deliberate
+ * difference from the Vercel deployment, not an oversight.
+ */
+export default defineSandbox({
+  backend: docker(),
+  revalidationKey: () => "kybernesis-workshop-v5-docker",
+  async bootstrap({ use }) {
+    const sandbox = await use();
+    await sandbox.run({ command: "apt-get update" });
+    await sandbox.run({ command: "npm install -g pnpm" });
+    await sandbox.run({
+      command:
+        "mkdir -p /workspace/.shot && cd /workspace/.shot && echo '{\\"name\\":\\"kyb-shot\\",\\"private\\":true}' > package.json && npm install playwright",
+    });
+    await sandbox.run({
+      command: "cd /workspace/.shot && npx playwright install --with-deps chromium",
+    });
+  },
+});
+`;
+    }
+    return `import { defineSandbox } from "eve/sandbox";
+import { vercel } from "eve/sandbox/vercel";
+
+/**
+ * The engineer workshop: a warm, safe cloud dev machine.
+ *
+ * TEMPLATE bootstrap (once, inherited by every session): pnpm + Playwright +
+ * Chromium. Prewarm runs at deploy time, so a broken bootstrap fails the build
+ * loudly and warm sessions run the full render→screenshot→vision loop in
+ * seconds. Backend PINNED to Vercel Sandbox — hosted sandboxes even from local
+ * dev (run \`vercel link\` + \`vercel env pull\` first), so evals exercise the
+ * exact production backend. No Docker anywhere.
+ *
+ * All sessions run under a domain ALLOWLIST: an agent that installs arbitrary
+ * npm packages must not have open egress. A blocked domain fails loudly;
+ * treat every addition as a security decision.
+ */
+export default defineSandbox({
+  backend: vercel({
+    resources: { vcpus: 4 },
+    networkPolicy: {
+      allow: [
+        "registry.npmjs.org",
+        "*.npmjs.org",
+        "github.com",
+        "api.github.com",
+        "codeload.github.com",
+        "*.githubusercontent.com",
+        "cdn.playwright.dev",
+        "playwright.azureedge.net",
+        "playwright.download.prss.microsoft.com",
+        "storage.googleapis.com",
+        "archive.ubuntu.com",
+        "security.ubuntu.com",
+        "ports.ubuntu.com",
+        "*.ubuntu.com",
+        "deb.debian.org",
+        "security.debian.org",
+        "*.debian.org",
+        "ai-gateway.vercel.sh",
+        "vercel.com",
+        "*.vercel.app",
+        "fonts.googleapis.com",
+        "fonts.gstatic.com",
+      ],
+    },
+  }),
+  revalidationKey: () => "kybernesis-workshop-v5",
+  async bootstrap({ use }) {
+    const sandbox = await use();
+    // The egress proxy carries HTTPS only; apt defaults to http:// mirrors, so
+    // every index fetch silently fails. Rewrite to https first.
+    await sandbox.run({
+      command:
+        "find /etc/apt -type f \\\\( -name '*.list' -o -name '*.sources' \\\\) -exec sed -i 's|http://|https://|g' {} + && apt-get update",
+    });
+    await sandbox.run({ command: "npm install -g pnpm" });
+    await sandbox.run({
+      command:
+        "mkdir -p /workspace/.shot && cd /workspace/.shot && echo '{\\"name\\":\\"kyb-shot\\",\\"private\\":true}' > package.json && npm install playwright",
+    });
+    await sandbox.run({
+      command: "cd /workspace/.shot && npx playwright install --with-deps chromium",
+    });
+  },
+});
+`;
+}
+export function engineerPlan(host, model) {
+    const onExe = host === "exe";
+    const files = [
+        {
+            path: "agent/subagents/builder/agent.ts",
+            content: onExe
+                ? `import { defineAgent } from "eve";
+import { createOpenAI } from "@ai-sdk/openai";
+import { exeModel } from "@kybernesis/exe";
+
+// The specialist the root agent delegates BUILDING to. \`description\` is what
+// the root routes on — keep it about building, not answering.
+export default defineAgent({
+  description:
+    "Builds and runs software: scaffolds projects, writes code, installs dependencies, runs builds and dev servers, and visually verifies rendered pages. Use when the user asks for something to be BUILT, prototyped, deployed, or fixed in code — not for questions, planning, or scheduling.",
+  model: exeModel({ model: process.env.EXE_MODEL ?? ${JSON.stringify(model)}, createOpenAI }),
+  modelContextWindowTokens: 200_000,
+});
+`
+                : `import { defineAgent } from "eve";
+
+// The specialist the root agent delegates BUILDING to. \`description\` is what
+// the root routes on — keep it about building, not answering.
+export default defineAgent({
+  description:
+    "Builds and runs software: scaffolds projects, writes code, installs dependencies, runs builds and dev servers, and visually verifies rendered pages. Use when the user asks for something to be BUILT, prototyped, deployed, or fixed in code — not for questions, planning, or scheduling.",
+  model: ${JSON.stringify(model)},
+});
+`,
+        },
+        {
+            path: "agent/subagents/builder/extensions/engineer.ts",
+            content: `// Engineer layer mounted LOCALLY on this subagent (eve >=0.30): screenshot,
+// deliver, and the trade-school skills belong to \`builder\` alone. The root
+// agent never gets shell or a browser.
+export { default } from "@kybernesis/engineer";
+`,
+        },
+        {
+            path: "agent/subagents/builder/sandbox/sandbox.ts",
+            content: workshopSandbox(host),
+        },
+    ];
+    if (onExe) {
+        files.push({
+            path: "agent/subagents/builder/tools/preview.ts",
+            content: `export { previewTool as default } from "@kybernesis/exe/preview";
+`,
+        });
+    }
+    return {
+        files,
+        deps: onExe ? ["@kybernesis/engineer", "@kybernesis/exe"] : ["@kybernesis/engineer"],
+        steps: onExe
+            ? [
+                "Enable Docker on the host (some images ship it disabled): sudo systemctl enable --now docker",
+                "Preview server (so the agent can show you what it built):\n       mkdir -p ~/preview && setsid python3 -m http.server 3456 --directory ~/preview &\n       then open https://<vm>.exe.xyz:3456/<file> (account-gated, not public)",
+                "File delivery needs object storage: set BLOB_READ_WRITE_TOKEN (Vercel Blob) or DELIVER_DIR + DELIVER_BASE_URL to serve from this host",
+                "Public deploys need the client's own Vercel token — Vercel Connect does NOT work off-Vercel",
+            ]
+            : [
+                "File delivery: vercel blob create-store <name>-deliverables --access public --yes",
+                "Preview deploys: eve add connection/vercel, then vercel connect create mcp.vercel.com --name vercel && vercel connect attach mcp.vercel.com/vercel --yes",
+            ],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent — plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",

package/skills/fde-engagement/references/playbook.md

@@ -40,6 +40,10 @@ npm create @kybernesis acme-atlas -- --engineer
 #    Prompts: display name · department subagents · control-plane issuer.
 #    (Non-interactive/CI: defaults apply when stdin is not a terminal.)
 
+# …or, when the client will NOT use Vercel — their own VM, or their own
+# ChatGPT/LLM subscription paying for inference. See section 11:
+npm create @kybernesis acme-atlas -- --host=exe --engineer
+
 # 3. (Optional, for repeated use) put `kyb` on the PATH for the whole engagement:
 npm install -g @kybernesis/create
 ```
@@ -1714,9 +1718,279 @@ the control-plane repo's seed scripts.)
 it is far faster than booting the dev server. `npx eve logs` reads the last `eve dev`
 diagnostic log if you need stderr, tool failures, and rebuild lines.
 
+### Self-hosted hosts (exe.dev / client infrastructure)
+
+**I deployed a change and the agent still does the old thing.**
+The restart did not take. Check that the running process started *after* the build
+(`scripts/eve-server.sh` asserts this and fails loudly). A silently-failed restart is the
+single most expensive failure mode off Vercel, because every test you run afterwards
+measures the previous build. If the process is current, start a **fresh conversation** —
+a long-lived channel session caches the compiled agent.
+
+**Every sandbox tool fails with `SandboxTemplateNotProvisionedError`.**
+Either Docker is installed but disabled (`sudo systemctl enable --now docker` — exeuntu
+ships it disabled), or the server was started as `node .output/server/index.mjs`, which
+skips the CLI's template prewarm. Start with `npx eve start`.
+
+**The subagent's screenshots fail with `Cannot find module 'playwright'` but the root
+agent is fine.**
+Subagents own their sandbox; they do not inherit the root's. Give the subagent its own
+`sandbox/sandbox.ts`.
+
+**My env vars are missing under `eve start`.**
+`eve start` does not read `.env.local` the way `eve dev` does. Use
+`scripts/eve-server.sh`, which exports it into the process.
+
+**I killed the agent and my own SSH session at the same time.**
+`pkill -f <pattern>` matches the SSH command line that contains the pattern. Keep kill
+patterns inside a script on the host; never pass them on an `ssh` command line.
+
+**A sandbox VM boots and shows `running`, but every command answers "command not found".**
+SSH is landing on exe.dev's lobby REPL rather than the VM. exe.dev reuses VM names, so a
+name deleted and recreated within a few minutes can keep resolving to the lobby, and a
+stale `known_hosts` entry does the same thing. Use a fresh name, and never reuse the
+caller's `known_hosts` for sandbox VMs.
+
+**A command works when I SSH in by hand but not from the agent.**
+A non-interactive SSH command does not source the login profile, so toolchains installed
+onto the profile PATH (nvm, pyenv, cargo) are invisible. Run through `bash -lc` — but not
+for file I/O, whose stdout must stay byte-clean.
+
+**exe.dev refuses to run commands with my API token.**
+It cannot. A key registered through an API token inherits that token's command scope, and
+shell exec is not a scoped command. Running commands needs a full-permission account key;
+see 11.6 for the isolation this demands.
+
+### Third-party APIs and connections
+
+**The agent reports that a service is down or that a resource "isn't shared" with it.**
+Verify before you believe it, and never change the client's permissions on an agent's
+say-so. An agent's error message is a hypothesis, not evidence — one real case reported an
+outage, then a permissions problem, while the data was reachable the entire time and the
+actual cause was a version header. Read the request and response yourself.
+
+**My manual `curl` works but the agent's identical call fails.**
+It is not identical — and the difference between the two requests *is* the bug. Diff them
+at the first contradiction rather than proving again that the token works. A version
+header, a content type, or a base URL differing by one path segment will do it.
+
+**Calls derived from a large OpenAPI spec fail in ways that make no sense.**
+Specs with ambiguous ID schemes (Notion's `database_id` vs `data_source_id` for the same
+object) make the model pick wrong, and the API's errors describe a different problem.
+Write a small purpose-built tool with the endpoint and IDs pinned; keep the generic
+connection for the long tail.
+
 ---
 
-## 11. Known gaps — state these plainly, do not sell around them
+
+## 11. Self-hosted deployments (when the client will not use Vercel)
+
+Vercel is the default path and the proven one. Take this track when the client
+**cannot or will not** put the agent on Vercel — procurement, data residency, an
+existing VM estate — or when they want inference billed to a subscription they
+already pay for rather than to a gateway.
+
+Everything else in this playbook still applies. This section covers only what
+changes.
+
+**The governing rule: every credential comes from the CLIENT's accounts.** If a
+step works only because you happen to hold a token, that step is a bug in the
+deployment, not a shortcut — it will fail on the real engagement, in front of
+the client. Assume you have no Vercel connection, no blob store, and no API
+keys of your own.
+
+### 11.1 Scaffold
+
+```bash
+kyb init <name> --host=exe --channel=<imessage|slack|telegram|none> --engineer
+cd <name> && kyb doctor
+```
+
+`--host=exe` swaps the host bindings; everything else is the same product —
+same memory, same evals, same control-plane wiring, same engineer layer.
+`kyb doctor` knows every failure mode below and fails loudly on each.
+
+### 11.2 What Vercel gives you that a client host does not
+
+| Capability | On Vercel | Self-hosted replacement |
+| --- | --- | --- |
+| Model access | AI Gateway | exe.dev LLM integration (`exeModel`) — managed, BYO key, or a **ChatGPT subscription** |
+| Slack / Photon / Linear credentials | Vercel Connect | **static credentials the client issues** |
+| Sandbox | `vercel()` | `docker()` on the host, or `exeSandbox()` per-task VMs |
+| File delivery | Vercel Blob | Blob **or** `DELIVER_DIR` + `DELIVER_BASE_URL` |
+| Public URLs | deployments | a deploy target, or an account-gated preview |
+| Secrets | Vercel env | host env + the platform's own secret injection |
+
+**Vercel Connect does not work off-Vercel — at all.** It authenticates via
+Vercel OIDC, which does not exist on another host. That applies to Slack, the
+Vercel MCP connection, Linear, everything. Each becomes a static credential
+someone must issue and rotate, and `kyb doctor` fails if a `@vercel/connect`
+import survives into a self-hosted agent.
+
+### 11.3 Host setup (exe.dev)
+
+```bash
+ssh exe.dev new --name <agent>
+ssh exe.dev share port <agent> 8000 && ssh exe.dev share set-public <agent>
+```
+
+Make the host public **before** registering any webhook — webhooks need
+anonymous access, and a provider that fails verification at registration time
+usually will not tell you why.
+
+Then, on the VM: Node 24, `npm ci`, `npx eve build`, and start through
+`scripts/eve-server.sh` from `@kybernesis/exe`.
+
+Three things that will cost you an afternoon if you skip them:
+
+- **`eve start` does not read `.env.local`** the way `eve dev` does. The
+  supervision script exports it into the process for you.
+- **Start via `npx eve start`, not `node .output/server/index.mjs`.** Sandbox
+  template prewarm lives in the CLI, not the built server. Starting the server
+  directly gives you cleaner logs and no prewarm, so every sandbox tool then
+  fails with `SandboxTemplateNotProvisionedError`.
+- **Docker ships disabled on some images**, exeuntu among them. `docker
+  --version` answers happily while nothing can actually run. Fix with `sudo
+  systemctl enable --now docker`.
+
+### 11.4 Model: billing inference to the client's subscription
+
+exe.dev brokers the model, so no provider key sits on the host:
+
+```bash
+ssh exe.dev integrations setup chatgpt --name work    # once, device-code flow
+ssh exe.dev integrations edit llm --openai=chatgpt --openai-account=work
+```
+
+Then `exeModel()` from `@kybernesis/exe` points the agent at it. A Codex-backed
+subscription requires `store: false` on every request; `exeModel` forces it.
+
+This is the single biggest commercial difference in the self-hosted track: a
+client with an existing ChatGPT or Claude subscription pays no incremental
+inference cost for the pilot. Say the number out loud in the discovery
+conversation — it changes the shape of the deal.
+
+### 11.5 Third-party APIs: broker the credential, pin the version
+
+Do not put a client's API token on the agent host. Put it in an exe.dev
+http-proxy integration, which injects headers server-side:
+
+```bash
+ssh exe.dev "integrations add http-proxy --name notion \
+  --target https://api.notion.com \
+  --header 'Authorization:Bearer <token>' \
+  --header 'Notion-Version:2025-09-03' \
+  --attach vm:<agent>"
+```
+
+The agent then calls `https://notion.int.exe.xyz` with no credential at all, and
+rotation happens in one place the client controls.
+
+Two rules here, both learned expensively:
+
+**Pin the API version the SPEC describes, not the one in a doc example.** A
+version header copied from documentation while the agent's OpenAPI spec
+describes a newer API produces errors that describe the wrong problem entirely.
+One real case cost most of a day: `Notion-Version: 2022-06-28` against a spec
+using `/v1/data_sources/...` returned `invalid_request_url`, intermittent 503s
+from search, and "not shared with the integration" — three different messages,
+none of them about the version mismatch, two of which look like a permissions
+or availability problem you can waste hours "fixing" on the client's side.
+
+**Use `--header` for the token, never `--bearer=-`.** The stdin form mangles the
+value and the API answers 401 "token is invalid".
+
+**Large specs with ambiguous ID schemes need a purpose-built tool, not a raw
+connection.** Notion's spec is ~1.2MB and splits `database_id` from
+`data_source_id` for the same object; a model deriving calls from it picks
+wrong. Pin the endpoint and the IDs in a small tool under `agent/tools/`, keep
+the generic connection for the long tail, and point the instructions at the
+tool. Reads went from unreliable to deterministic with about sixty lines.
+
+### 11.6 The engineer layer, self-hosted
+
+`--engineer` scaffolds a **builder subagent** that owns the build capability, so
+the root agent never gets a shell. It comes with the full production loop —
+workshop sandbox, Playwright, screenshots, visual verification, delivery — not a
+reduced version of the Vercel one.
+
+- **Subagents own their sandbox; they do NOT inherit the root's.** A builder
+  without its own `sandbox/sandbox.ts` gets a bare template and every screenshot
+  fails with `Cannot find module 'playwright'` while the root's template is
+  fine. `kyb doctor` checks for this.
+- Conversely, if the root agent runs no code, it needs **no** root sandbox.
+  Leaving one there costs a full template prewarm on every deploy for nothing.
+
+**Choosing a sandbox backend:**
+
+`docker()` on the agent's own VM is the default and the safer choice. Reach for
+`exeSandbox()` — a whole exe.dev VM per session, with Docker available *inside*
+it and its own public URL — only when the work needs real isolation or
+per-session compute.
+
+`exeSandbox()` carries one hard constraint you must raise with the client before
+choosing it: **it needs a full-permission account SSH key.** exe.dev keys
+registered through an API token inherit that token's command scope and cannot
+open a shell at all, so there is no scoped credential that can run commands. The
+key it does need grants shell to **every VM on that exe.dev account**. The
+backend therefore refuses to start unless the account is dedicated to this agent
+(its own VM plus its sandboxes), naming any foreign VMs it finds. Overriding
+that with `allowSharedAccount: true` is a decision for the client to make in
+writing, not for you to make on their behalf. VM lifecycle stays on a separately
+scoped token that cannot exec, so neither credential is sufficient alone.
+
+### 11.7 Showing the client what the agent built
+
+- **Vercel Blob refuses to serve HTML inline** — it forces a download. Use it
+  for documents and exports, never to show a web page.
+- **exe.dev forwards ports 3000–9999** to `https://<vm>.exe.xyz:<port>/`, but a
+  VM has exactly **one public port** and the agent's webhook already owns it.
+  Alternate ports are account-gated: fine for the client reviewing work, not for
+  the public.
+- **Anything genuinely public needs a deploy target** — the client's own Vercel
+  token, or their hosting. Treat "public" as a deploy step, not a toggle, and
+  price it into the scope.
+- A sandbox is a container: its ports are not reachable from the host, so a dev
+  server inside it cannot be previewed directly. Copy the artifact out (the
+  `preview` tool in `@kybernesis/exe`) or deploy it.
+
+### 11.8 Prove the restart, every time
+
+There is no deployment pipeline here to tell you a release landed. A restart
+that silently fails leaves the agent serving a stale build — new connections,
+tools, and instructions never appear — and **every test you run afterwards
+measures yesterday's agent.** One session lost an hour to exactly this.
+
+`scripts/eve-server.sh` asserts the running process started *after* the build it
+should be serving, and fails loudly when it did not. Use it rather than
+`pkill` + `npx eve start` by hand. Related: `pkill -f <pattern>` over SSH kills
+your own session when the pattern appears in the SSH command line — and can take
+the agent down with it. Use the pidfile.
+
+Also: a long-lived channel session caches the compiled agent. After changing
+capabilities, start a **fresh conversation** before deciding the change did not
+work.
+
+### 11.9 Credential checklist — collect ALL of these from the client
+
+Nothing here can be borrowed from another agent or another account.
+
+1. **Host** — VM/server, plus the platform token if the agent provisions anything
+2. **Model source** — their LLM API key, gateway allocation, or connected subscription
+3. **Channel app** — their Slack app (bot + app token) / Photon project / bot token
+4. **Arcana** — workspaces + scoped `kb_` keys (one per brain, plus `-eval`)
+5. **Storage for deliverables** — their blob store, or a served host directory
+6. **Deploy target** — their Vercel token or hosting, if the agent ships sites
+7. **Sandbox credentials** — only if using `exeSandbox()` (see 11.6)
+8. **Control plane** — agent registered and the pilot cohort granted
+
+### 11.10 Before calling it done
+
+`kyb doctor` green (or every warning consciously accepted), the eval suite green
+against the client's `-eval` workspace, and a live turn on the real surface —
+sent from the client's own device, not yours.
+
+## 12. Known gaps — state these plainly, do not sell around them
 
 Being straight about these is a feature. Clients have met vendors who were not.
 

package/skills/self-hosting/SKILL.md

@@ -0,0 +1,146 @@
+---
+description: Use when deploying an eve agent OFF Vercel — on exe.dev, a VPS, or any client infrastructure — or when a client wants to use their own ChatGPT/LLM subscription. Covers what breaks, what replaces it, and the credential checklist.
+---
+
+# Self-hosted agents (client infrastructure, not Vercel)
+
+The Vercel path is the default and the proven one. Reach for this when the
+client **won't or can't use Vercel**, or wants their agent's inference billed to
+a subscription they already pay for.
+
+**The governing rule: everything must come from the CLIENT's accounts.** If a
+step only works because you happen to hold a credential, that step is a bug in
+the deployment, not a shortcut. It will fail on the real engagement.
+
+## Scaffold
+
+```bash
+kyb init <name> --host=exe --channel=<imessage|slack|telegram|none> --engineer
+```
+
+`--host=exe` swaps the bindings; everything else is the same product. Run
+`kyb doctor` after — it knows the self-hosted failure modes below.
+
+## What Vercel gives you that a client host does not
+
+| Capability | On Vercel | Self-hosted replacement |
+| --- | --- | --- |
+| Model access | AI Gateway | exe.dev LLM integration (`exeModel`) — managed, BYO key, or a **ChatGPT subscription** |
+| Slack/Photon/Linear credentials | Vercel Connect | **Portable/static credentials the client issues** |
+| Sandbox | `vercel()` hosted | `docker()` on the host |
+| File delivery | Vercel Blob | Blob **or** `DELIVER_DIR` + `DELIVER_BASE_URL` |
+| Public URLs | deployments | a deploy target, or an account-gated preview |
+| Secrets | Vercel env | host env + the platform's own secret injection |
+
+**Vercel Connect does not work off-Vercel — at all.** It authenticates via
+Vercel OIDC, which does not exist on another host. That applies to Slack, the
+Vercel MCP connection, Linear, everything. Each becomes a static credential
+someone must issue and rotate. `kyb doctor` fails loudly if a `@vercel/connect`
+import survives into a self-hosted agent.
+
+## The failure modes, each of which cost a real session
+
+- **Docker ships disabled on some images.** exe.dev's exeuntu runs
+  `systemctl disable docker.service`, so `docker --version` works while nothing
+  can run. Every sandbox call fails with `SandboxTemplateNotProvisionedError`.
+  Fix: `sudo systemctl enable --now docker`.
+- **Subagents own their sandbox — they do NOT inherit the root's.** An engineer
+  subagent without its own `sandbox/sandbox.ts` gets a bare template, and the
+  screenshot tool fails with `Cannot find module 'playwright'` while the root's
+  template is fine.
+- **`eve start` does not read `.env.local`** the way `eve dev` does. Export it
+  into the process (`scripts/eve-server.sh` in `@kybernesis/exe` does this).
+- **Prewarm lives in the eve CLI, not the built server.** Starting
+  `node .output/server/index.mjs` directly gives you clean logs but skips
+  template prewarm entirely. Start with `npx eve start`.
+- **`localDev()` never authenticates under `eve start`** — it is a property of
+  the deployment, not the request. A self-hosted agent needs a real
+  authenticator from day one.
+- **`pkill -f <pattern>` over SSH kills your own session** when the pattern
+  appears in the SSH command line — and can take the agent with it. Use a
+  pidfile (`scripts/eve-server.sh`).
+- **Never diagnose "nothing is happening" from a log file.** Count runs on disk:
+  `.eve/.workflow-data/runs/`. A log can look frozen at boot while the agent
+  serves happily.
+
+## Showing the client what the agent built
+
+- **Vercel Blob refuses to serve HTML inline** — it forces a download. Use it
+  for documents and exports, never to show a web page.
+- **exe.dev forwards ports 3000–9999** to `https://<vm>.exe.xyz:<port>/`, but a
+  VM has exactly **one public port** and the agent's webhook already owns it.
+  Alternate ports are account-gated: fine for the client reviewing work, not for
+  the public.
+- **Anything genuinely public needs a deploy target** — the client's own Vercel
+  token, or their hosting. Treat "public" as a deploy step, not a toggle.
+- A sandbox is a container: its ports are not reachable from the host, so a dev
+  server inside it cannot be previewed directly. Copy the artifact out (the
+  `preview` tool in `@kybernesis/exe`) or deploy it.
+
+## Credential checklist — collect ALL of these from the client
+
+Nothing here can be borrowed from another agent or another account.
+
+1. **Host** — VM/server, plus the platform token if the agent provisions anything
+2. **Model source** — their LLM API key, gateway allocation, or connected
+   subscription (exe: `integrations setup chatgpt`, then `integrations edit llm`)
+3. **Channel app** — their Slack app (bot + app token) / Photon project / bot token
+4. **Arcana** — workspaces + scoped `kb_` keys (one per brain, plus `-eval`)
+5. **Storage for deliverables** — their blob store, or a served host directory
+6. **Deploy target** — their Vercel token or hosting, if the agent ships sites
+7. **Control plane** — agent registered and the pilot cohort granted
+
+## Before calling it done
+
+`kyb doctor` green (or every warning consciously accepted), the eval suite green
+against the client's `-eval` workspace, and a live turn on the real surface.
+
+## Third-party APIs: version pinning and spec-derived calls
+
+Two failures here cost most of a day on the first deployment. Both look like
+outages or permission problems and are neither.
+
+**Pin the API version the SPEC describes, not the one in a doc example.**
+Notion's OpenAPI spec describes their current API (`/v1/data_sources/…`), but
+eve's docs example pins `Notion-Version: 2022-06-28`, where that endpoint does
+not exist. The mismatch returns `invalid_request_url`, `service_unavailable`
+(503) on search, and "not shared with the integration" — three different lies,
+none of them about the actual problem. Verify by making the SAME call the agent
+makes, headers included.
+
+**When the agent and your manual test disagree, the difference between the two
+requests IS the bug.** Diff them at the first contradiction. Repeatedly proving
+"the token works" with a hand-written curl while the agent fails proves nothing
+if your curl sends a different version header.
+
+**An agent's error message is a hypothesis, not evidence.** It will confidently
+report an outage or a permissions problem it has not verified. Read the actual
+request and response before acting — and never change a client's permissions on
+an agent's say-so.
+
+**Large specs with ambiguous ID schemes need a purpose-built tool, not a raw
+connection.** Notion's spec is ~1.2MB and splits `database_id` from
+`data_source_id` for the same board; a model deriving calls from it picks the
+wrong one. Pin the endpoint and the IDs in a small tool
+(`agent/tools/<domain>.ts`), keep the generic connection for the long tail, and
+point the instructions at the tool.
+
+**Credential brokering (exe http-proxy) is the right default off-Vercel:**
+
+```
+integrations add http-proxy --name <svc> --target https://api.example.com \
+  --header 'Authorization:Bearer <token>' --header '<Version-Header>:<value>' \
+  --attach vm:<vm>
+```
+
+Use `--header` for the token, not `--bearer=-`: the stdin form mangles it and
+the API answers 401 "token is invalid".
+
+## Restarts must be proven, not assumed
+
+A restart that silently fails leaves the agent serving a stale build — new
+connections, tools, and instructions never appear, and every later test measures
+yesterday's agent. Assert the process started AFTER the build it should serve
+(`scripts/eve-server.sh` and the restart pattern in `@kybernesis/exe` do this).
+Related: a long-lived channel session caches the compiled agent, so start a
+fresh conversation after changing capabilities.