nylorun 0.7.0-beta → 0.9.0-beta

package/dist/stack/env-file.js

@@ -1,21 +1,30 @@
-import { DERIVED_PRINCIPAL_ID_PATTERN } from "@nylorun/core/compatibility";
 import { parseFrameAncestors } from "@nylorun/core/contracts";
 import { CliError } from "../errors.js";
 /**
- * Origins that may embed Studio by default: Babai Desktop's `nylorun` scheme on
- * macOS and Linux, and its WebView2 origin on Windows (Studio §8.9).
+ * Origins that may embed Studio by default: none. Embedding is opt-in: the operator lists
+ * the exact origins of the app that frames Studio (`--studio-embed-origin`, Studio §8.9).
  */
-export const DEFAULT_STUDIO_FRAME_ANCESTORS = [
-    "nylorun://localhost",
-    "http://nylorun.localhost",
-];
+export const DEFAULT_STUDIO_FRAME_ANCESTORS = [];
+const SANDBOX_KEYS = {
+    token: "NYLORUN_SANDBOXES_TOKEN",
+    image: "NYLORUN_SANDBOXES_IMAGE",
+    harnessPort: "NYLORUN_SANDBOX_HARNESS_PORT",
+    gatesPort: "NYLORUN_SANDBOX_GATES_PORT",
+    egressPort: "NYLORUN_SANDBOX_EGRESS_PORT",
+    hostAddress: "NYLORUN_SANDBOX_HOST_ADDRESS",
+    bind: "NYLORUN_SANDBOX_BIND",
+};
 const KEYS = {
     runtimePort: "NYLORUN_PORT",
     adminPort: "NYLORUN_ADMIN_PORT",
     studioPort: "NYLORUN_STUDIO_PORT",
     restatePort: "NYLORUN_RESTATE_PORT",
+    restateUi: "NYLORUN_RESTATE_UI",
     postgresPassword: "NYLORUN_POSTGRES_PASSWORD",
     gatesToken: "NYLORUN_GATES_TOKEN",
+    harnessToken: "NYLORUN_HARNESS_TOKEN",
+    harness: "NYLORUN_HARNESS",
+    objectStoreSecretKey: "NYLORUN_OBJECT_STORE_SECRET_KEY",
     restateIdentityKey: "NYLORUN_RESTATE_IDENTITY_KEY",
     uid: "NYLORUN_UID",
     gid: "NYLORUN_GID",
@@ -25,7 +34,6 @@ const KEYS = {
     studioFrameAncestors: "NYLORUN_STUDIO_FRAME_ANCESTORS",
     studioAnalyticsId: "NYLORUN_STUDIO_ANALYTICS_ID",
     tenantName: "NYLORUN_TENANT_NAME",
-    derivedPrincipals: "NYLORUN_DERIVED_PRINCIPALS",
 };
 /** Compose .env values: single quotes keep a value literal (no interpolation). */
 function quote(key, value) {
@@ -42,17 +50,25 @@ function unquote(value) {
     return trimmed;
 }
 export function renderEnvFile(env) {
-    const line = (field) => `${KEYS[field]}=${quote(KEYS[field], String(env[field]))}`;
+    const line = (field) => {
+        const value = env[field];
+        return `${KEYS[field]}=${quote(KEYS[field], typeof value === "boolean" ? (value ? "1" : "0") : String(value))}`;
+    };
+    const sandboxes = env.sandboxes;
+    const sandboxLine = (field) => `${SANDBOX_KEYS[field]}=${quote(SANDBOX_KEYS[field], String(sandboxes[field]))}`;
     return [
-        "# Written by `nylorun start`. Mode 0600: holds the Postgres password and the",
-        "# gates token. Ports, the password and the token are kept across starts;",
-        "# images, UID/GID and the Host root are refreshed on every start.",
+        "# Written by `nylorun start`. Mode 0600: holds the Postgres password, the gates",
+        "# token and the Object store's secret key. Ports and secrets are kept across",
+        "# starts; images, UID/GID and the Host root are refreshed on every start.",
         "",
         "# Published on 127.0.0.1; clients use http://localhost:<port>.",
         line("runtimePort"),
         line("adminPort"),
         line("studioPort"),
+        "# Restate's UI and admin (unauthenticated) are published only with",
+        "# nylorun start --restate-ui (or NYLORUN_RESTATE_UI=1); decided on every start.",
         line("restatePort"),
+        line("restateUi"),
         "",
         line("postgresPassword"),
         "",
@@ -60,6 +76,16 @@ export function renderEnvFile(env) {
         "# model call.",
         line("gatesToken"),
         "",
+        "# The harness container presents this token to the runtime's Harness API; it",
+        "# holds no other credential. NYLORUN_HARNESS=in-process runs agent turns, MCP",
+        "# servers and workspaces in the runtime container instead (rollback); kept.",
+        line("harnessToken"),
+        line("harness"),
+        "",
+        "# RustFS (the Object store) accepts this secret key; only the runtime and the",
+        "# gateway receive it.",
+        line("objectStoreSecretKey"),
+        "",
         "# Restate signs requests to the Runtime's Worker endpoint with the private",
         "# key in restate-identity.pem; the Runtime accepts only this public key.",
         line("restateIdentityKey"),
@@ -73,8 +99,8 @@ export function renderEnvFile(env) {
         line("runtimeImage"),
         line("studioImage"),
         "",
-        "# Exact origins that may show Studio in a frame (Babai Desktop). Kept across",
-        "# starts; change with nylorun start --studio-embed-origin <origin>.",
+        "# Exact origins that may show Studio in a frame; none by default. Kept across",
+        "# starts; add with nylorun start --studio-embed-origin <origin>.",
         line("studioFrameAncestors"),
         "",
         "# Studio's anonymous usage analytics; empty when off. Set on every start: turn",
@@ -82,27 +108,25 @@ export function renderEnvFile(env) {
         line("studioAnalyticsId"),
         "",
         "# The Tenant's name, which the Runtime gives the Tenant it creates on the first",
-        "# start, and the derived principals it registers on that Tenant (keys derived",
-        "# from the admin key; `project` is the Project link's).",
+        "# start.",
         line("tenantName"),
-        line("derivedPrincipals"),
         "",
+        ...(sandboxes
+            ? [
+                "# Sandboxes (nylorun sandbox enable): the runtime's token for the sandboxes",
+                "# service, its image, and the host ports pods reach on the host address.",
+                sandboxLine("token"),
+                sandboxLine("image"),
+                sandboxLine("harnessPort"),
+                sandboxLine("gatesPort"),
+                sandboxLine("egressPort"),
+                sandboxLine("hostAddress"),
+                sandboxLine("bind"),
+                "",
+            ]
+            : []),
     ].join("\n");
 }
-/**
- * `NYLORUN_DERIVED_PRINCIPALS`: comma-separated principal ids, as the Runtime accepts them
- * (not `studio`), with `project` first so the Project link's key always works.
- */
-export function parseDerivedPrincipals(raw, source) {
-    const ids = raw
-        .split(",")
-        .map((entry) => entry.trim())
-        .filter((entry) => entry !== "");
-    for (const id of ids)
-        if (!DERIVED_PRINCIPAL_ID_PATTERN.test(id) || id === "studio")
-            throw new CliError(`${source} has '${id}': each entry must match ${DERIVED_PRINCIPAL_ID_PATTERN} and not be studio.`, 2);
-    return [...new Set(["project", ...ids])];
-}
 /** Parse KEY=value lines; comments and blank lines are skipped. */
 export function parseEnvLines(text) {
     const values = new Map();
@@ -123,6 +147,24 @@ function port(value) {
     const n = Number(value);
     return n >= 1 && n <= 65535 ? n : undefined;
 }
+const IPV4 = /^(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)$/;
+/** The sandboxes section, when complete and valid. */
+function parseSandboxes(values) {
+    const token = values.get(SANDBOX_KEYS.token);
+    const image = values.get(SANDBOX_KEYS.image);
+    const harnessPort = port(values.get(SANDBOX_KEYS.harnessPort));
+    const gatesPort = port(values.get(SANDBOX_KEYS.gatesPort));
+    const egressPort = port(values.get(SANDBOX_KEYS.egressPort));
+    const hostAddress = values.get(SANDBOX_KEYS.hostAddress);
+    const bind = values.get(SANDBOX_KEYS.bind);
+    if (!token || !/^[0-9a-f]{64,}$/i.test(token) || !image)
+        return undefined;
+    if (!harnessPort || !gatesPort || !egressPort)
+        return undefined;
+    if (!hostAddress || !IPV4.test(hostAddress) || !bind || !IPV4.test(bind))
+        return undefined;
+    return { token, image, harnessPort, gatesPort, egressPort, hostAddress, bind };
+}
 export function parsePersisted(text) {
     const values = parseEnvLines(text);
     const out = {};
@@ -138,21 +180,26 @@ export function parsePersisted(text) {
     const restatePort = port(values.get(KEYS.restatePort));
     if (restatePort)
         out.restatePort = restatePort;
+    if (values.get(KEYS.restateUi) === "1")
+        out.restateUi = true;
     const password = values.get(KEYS.postgresPassword);
     if (password && /^[A-Za-z0-9]{16,}$/.test(password))
         out.postgresPassword = password;
     const gatesToken = values.get(KEYS.gatesToken);
     if (gatesToken && /^[0-9a-f]{64,}$/i.test(gatesToken))
         out.gatesToken = gatesToken;
-    const principals = values.get(KEYS.derivedPrincipals);
-    if (principals !== undefined) {
-        try {
-            out.derivedPrincipals = parseDerivedPrincipals(principals, `${KEYS.derivedPrincipals} in docker/.env`);
-        }
-        catch {
-            /* rewritten from the default on the next start */
-        }
-    }
+    const harnessToken = values.get(KEYS.harnessToken);
+    if (harnessToken && /^[0-9a-f]{64,}$/i.test(harnessToken))
+        out.harnessToken = harnessToken;
+    const harness = values.get(KEYS.harness);
+    if (harness === "remote" || harness === "in-process")
+        out.harness = harness;
+    const objectStoreSecretKey = values.get(KEYS.objectStoreSecretKey);
+    if (objectStoreSecretKey && /^[0-9a-f]{64}$/i.test(objectStoreSecretKey))
+        out.objectStoreSecretKey = objectStoreSecretKey;
+    const sandboxes = parseSandboxes(values);
+    if (sandboxes)
+        out.sandboxes = sandboxes;
     const ancestors = values.get(KEYS.studioFrameAncestors);
     if (ancestors !== undefined) {
         try {

package/dist/stack/host-files.js

@@ -26,7 +26,17 @@ async function writeAtomic(path, text) {
 }
 /** The Host root layout, mode 0700. */
 export async function ensureHostLayout(paths) {
-    for (const dir of [paths.root, paths.home, paths.tmp, paths.tenant, paths.keys, paths.docker])
+    // The harness container's mounts exist before Compose binds them (else Docker makes them as root).
+    for (const dir of [
+        paths.root,
+        paths.home,
+        paths.tmp,
+        paths.tenant,
+        ...Object.values(paths.harness),
+        paths.plugins,
+        paths.keys,
+        paths.docker,
+    ])
         await mkdir(dir, { recursive: true, mode: 0o700 });
 }
 export async function readHostConfig(paths) {

package/dist/stack/images.d.ts

@@ -1,20 +1,26 @@
 /**
  * Images a local Tenant runs. The Runtime and Studio tags are pinned by this
  * CLI release; `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them
- * (local builds, CI images). Postgres, Restate and s2-lite are the official
- * images, pinned here.
+ * (local builds, CI images). The sandboxes service (`nylorun sandbox enable`) is
+ * versioned with the Runtime: `ghcr.io/nylorun/sandboxes:<runtime pin>`, or
+ * `NYLORUN_SANDBOXES_IMAGE`. Postgres, Restate, s2-lite and RustFS are the
+ * official images, pinned here; RustFS (the Object store, D35) by digest as well, so
+ * it is upgraded only on purpose.
  */
 export declare const PINNED_IMAGES: {
     readonly postgres: "postgres:17.11";
     readonly restate: "docker.restate.dev/restatedev/restate:1.7.12";
     readonly s2: "ghcr.io/s2-streamstore/s2:0.43.0";
+    readonly rustfs: "rustfs/rustfs:1.0.1@sha256:1803faef57627e2d9c2e7d89d655d712ddded5389040054987163043fecb6a3c";
 };
 export interface StackImages {
     runtime: string;
     studio: string;
+    sandboxes: string;
     postgres: string;
     restate: string;
     s2: string;
+    rustfs: string;
 }
 /** `NYLORUN_RUNTIME_IMAGE` names the Runtime image, so its version is unknown here. */
 export declare function runtimeImageOverridden(env: Readonly<Record<string, string | undefined>>): boolean;

package/dist/stack/images.js

@@ -2,13 +2,17 @@ import { pinnedVersion } from "./versions.js";
 /**
  * Images a local Tenant runs. The Runtime and Studio tags are pinned by this
  * CLI release; `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them
- * (local builds, CI images). Postgres, Restate and s2-lite are the official
- * images, pinned here.
+ * (local builds, CI images). The sandboxes service (`nylorun sandbox enable`) is
+ * versioned with the Runtime: `ghcr.io/nylorun/sandboxes:<runtime pin>`, or
+ * `NYLORUN_SANDBOXES_IMAGE`. Postgres, Restate, s2-lite and RustFS are the
+ * official images, pinned here; RustFS (the Object store, D35) by digest as well, so
+ * it is upgraded only on purpose.
  */
 export const PINNED_IMAGES = {
     postgres: "postgres:17.11",
     restate: "docker.restate.dev/restatedev/restate:1.7.12",
     s2: "ghcr.io/s2-streamstore/s2:0.43.0",
+    rustfs: "rustfs/rustfs:1.0.1@sha256:1803faef57627e2d9c2e7d89d655d712ddded5389040054987163043fecb6a3c",
 };
 function override(env, name) {
     const value = env[name]?.trim();
@@ -27,6 +31,8 @@ export function stackImages(env, versions = {
             `ghcr.io/nylorun/runtime:${versions.runtime}`,
         studio: override(env, "NYLORUN_STUDIO_IMAGE") ??
             `ghcr.io/nylorun/studio:${versions.studio}`,
+        sandboxes: override(env, "NYLORUN_SANDBOXES_IMAGE") ??
+            `ghcr.io/nylorun/sandboxes:${versions.runtime}`,
         ...PINNED_IMAGES,
     };
 }

package/dist/stack/index.d.ts

@@ -7,6 +7,15 @@ export type { Check, DockerChecks } from "./docker.js";
 export declare function defaultStackDeps(env: Readonly<Record<string, string | undefined>>): StackDeps;
 /** Entry for `nylorun start|stop|status|logs|reset|studio|ls|delete`. */
 export declare function stackCommand(name: string, args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
+/** Entry for `nylorun sandbox ls|rm`. */
+export declare function sandboxCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
+export { sandboxUsage } from "./sandbox.js";
+/** Entry for `nylorun mcp connect`. */
+export declare function mcpCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
+export { mcpUsage } from "./mcp.js";
+/** Entry for `nylorun key put|list|rm`. */
+export declare function keyCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
+export { keyUsage } from "./keys.js";
 /** `nylorun studio`, landing on `next` when given, else on the Tenant's page. */
 export declare function studioCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>, options?: {
     next?: string;

package/dist/stack/index.js

@@ -2,6 +2,9 @@ import { spawn } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { runStackCommand, runStudioCommand } from "./commands.js";
 import { spawnDocker } from "./docker.js";
+import { keyCommand as runKeyCommand } from "./keys.js";
+import { sandboxCommand as runSandboxCommand } from "./sandbox.js";
+import { mcpCommand as runMcpCommand } from "./mcp.js";
 import { pinnedVersion } from "./versions.js";
 import { loopbackPorts } from "./ports.js";
 export { ensureStack, isStackCommand, readStackStatus, stackUsage, studioLoginUrl, tenantStudioPath, STACK_SERVICES, } from "./commands.js";
@@ -19,7 +22,6 @@ function browserCommand(env) {
  */
 const STACK_ENV_OWNED = [
     "NYLORUN_TENANT_NAME",
-    "NYLORUN_DERIVED_PRINCIPALS",
     "NYLORUN_STUDIO_ANALYTICS_ID",
 ];
 /** Real dependencies: docker on PATH, global fetch, the terminal. */
@@ -79,6 +81,21 @@ export function defaultStackDeps(env) {
 export async function stackCommand(name, args, env) {
     return await runStackCommand(name, args, defaultStackDeps(env));
 }
+/** Entry for `nylorun sandbox ls|rm`. */
+export async function sandboxCommand(args, env) {
+    return await runSandboxCommand(defaultStackDeps(env), args);
+}
+export { sandboxUsage } from "./sandbox.js";
+/** Entry for `nylorun mcp connect`. */
+export async function mcpCommand(args, env) {
+    return await runMcpCommand(defaultStackDeps(env), args);
+}
+export { mcpUsage } from "./mcp.js";
+/** Entry for `nylorun key put|list|rm`. */
+export async function keyCommand(args, env) {
+    return await runKeyCommand(defaultStackDeps(env), args);
+}
+export { keyUsage } from "./keys.js";
 /** `nylorun studio`, landing on `next` when given, else on the Tenant's page. */
 export async function studioCommand(args, env, options = {}) {
     return await runStudioCommand(args, defaultStackDeps(env), options);

package/dist/stack/keys.d.ts

@@ -0,0 +1,4 @@
+import { type StackDeps } from "./commands.js";
+export declare const keyUsage = "  key put <id> [--tenant <name>]     create the Tenant's key <id>, or rotate it (the old key stops working); prints the key once\n  key list [--tenant <name>] [--json] the Tenant's keys: id, role, when issued (never the keys)\n  key rm <id> [--tenant <name>]      delete key <id>: it stops working at once";
+/** `nylorun key <put|list|rm> ...` */
+export declare function keyCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/stack/keys.js

@@ -0,0 +1,72 @@
+/**
+ * `nylorun key put | list | rm`: the running local Tenant's operator keys (F9 I1, Host feature
+ * `operator-keys`), through its Admin API with the admin key. Revocable application keys by
+ * name, for app servers and other clients; none of these starts the Tenant.
+ */
+import { CliError } from "../errors.js";
+import { parseStackFlags, runningAdmin } from "./commands.js";
+import { deleteOperatorKey, listOperatorKeys, putOperatorKey } from "./operator-keys.js";
+export const keyUsage = `  key put <id> [--tenant <name>]     create the Tenant's key <id>, or rotate it (the old key stops working); prints the key once
+  key list [--tenant <name>] [--json] the Tenant's keys: id, role, when issued (never the keys)
+  key rm <id> [--tenant <name>]      delete key <id>: it stops working at once`;
+const usageError = (message) => new CliError(message, 2);
+async function put(deps, args) {
+    const usage = "nylorun key put <id> [--tenant <name>]";
+    const flags = parseStackFlags(args, { values: ["--tenant"] }, usage);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${usage}`);
+    const id = flags.rest[0];
+    const name = flags.values.get("--tenant");
+    const admin = await runningAdmin(deps, name === undefined ? {} : { name });
+    const key = await putOperatorKey(admin, id);
+    // The key alone on stdout, for scripts; it is not shown again.
+    deps.out(key.key);
+    deps.err(`${key.rotated ? "Rotated" : "Created"} key ${key.id} on Tenant ${admin.name}${key.rotated ? " (the previous key no longer works)" : ""}. Store it now: it is not shown again.`);
+    return 0;
+}
+async function list(deps, args) {
+    const usage = "nylorun key list [--tenant <name>] [--json]";
+    const flags = parseStackFlags(args, { booleans: ["--json"], values: ["--tenant"] }, usage);
+    if (flags.rest.length)
+        throw usageError(`Usage: ${usage}`);
+    const name = flags.values.get("--tenant");
+    const admin = await runningAdmin(deps, name === undefined ? {} : { name });
+    const keys = await listOperatorKeys(admin);
+    if (flags.booleans.has("--json")) {
+        deps.out(JSON.stringify(keys, null, 2));
+        return 0;
+    }
+    const rows = [["ID", "ROLE", "CREATED"], ...keys.map((key) => [key.id, key.role, key.createdAt])];
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    for (const row of rows)
+        deps.out(row
+            .map((cell, column) => (column === row.length - 1 ? cell : cell.padEnd(widths[column])))
+            .join("  "));
+    return 0;
+}
+async function rm(deps, args) {
+    const usage = "nylorun key rm <id> [--tenant <name>]";
+    const flags = parseStackFlags(args, { values: ["--tenant"] }, usage);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${usage}`);
+    const id = flags.rest[0];
+    const name = flags.values.get("--tenant");
+    const admin = await runningAdmin(deps, name === undefined ? {} : { name });
+    if (!(await deleteOperatorKey(admin, id))) {
+        deps.err(`No key ${id} on Tenant ${admin.name}.`);
+        return 1;
+    }
+    deps.out(`Deleted key ${id}: it no longer works.`);
+    return 0;
+}
+/** `nylorun key <put|list|rm> ...` */
+export async function keyCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "put")
+        return put(deps, rest);
+    if (sub === "list" || sub === "ls")
+        return list(deps, rest);
+    if (sub === "rm" || sub === "delete")
+        return rm(deps, rest);
+    throw usageError(`Usage:\n${keyUsage}`);
+}

package/dist/stack/mcp.d.ts

@@ -0,0 +1,8 @@
+import { type StackDeps } from "./commands.js";
+export declare const mcpUsage = "  mcp connect <url> --server <name> [--vault <id>] [--client-id <id>] [--tenant <name>] [--no-open]\n                                      sign the Tenant in to a remote MCP server with OAuth; the credential goes to the\n                                      installation vault mcp (or --vault), which sessions attach";
+/** The installation vault `connect` uses unless `--vault` names one. */
+export declare const MCP_VAULT_NAME = "mcp";
+/** How long `connect` waits for the browser sign-in: the Runtime keeps it for ten minutes. */
+export declare const CONNECT_TIMEOUT_MS: number;
+/** `nylorun mcp <connect> ...` */
+export declare function mcpCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/stack/mcp.js

@@ -0,0 +1,114 @@
+/**
+ * `nylorun mcp connect <url> --server <name>`: signs the running local Tenant in to a remote MCP
+ * server with OAuth (F9 C2), through its Tenant API with an operator key (`runningTenantApi`).
+ * The Runtime's keys module runs discovery, registration and the code exchange and seals the
+ * credential in an installation vault (`mcp` unless `--vault` names one); this command only
+ * opens the browser and waits for the credential to appear. It never starts the Tenant.
+ */
+import { randomUUID } from "node:crypto";
+import { PROTOCOL_HEADER, PROTOCOL_VERSION } from "@nylorun/core/compatibility";
+import { CliError } from "../errors.js";
+import { parseStackFlags, runningTenantApi } from "./commands.js";
+export const mcpUsage = `  mcp connect <url> --server <name> [--vault <id>] [--client-id <id>] [--tenant <name>] [--no-open]
+                                      sign the Tenant in to a remote MCP server with OAuth; the credential goes to the
+                                      installation vault mcp (or --vault), which sessions attach`;
+/** The installation vault `connect` uses unless `--vault` names one. */
+export const MCP_VAULT_NAME = "mcp";
+/** How long `connect` waits for the browser sign-in: the Runtime keeps it for ten minutes. */
+export const CONNECT_TIMEOUT_MS = 10 * 60_000;
+const usageError = (message) => new CliError(message, 2);
+async function call(deps, api, method, path, body) {
+    const response = await deps.fetch(`${api.runtimeUrl}${path}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${api.applicationKey}`,
+            [PROTOCOL_HEADER]: String(PROTOCOL_VERSION),
+            accept: "application/json",
+            ...(body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        redirect: "error",
+        signal: AbortSignal.timeout(150_000),
+    });
+    const answer = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        throw new CliError(`${method} ${path} returned ${response.status}${typeof answer.message === "string" ? `: ${answer.message}` : ""}`, 1);
+    return answer;
+}
+/** The URL as the vault binds it: origin, path and query, no default port, no fragment. */
+function bindingUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw usageError(`${input} is not a URL.`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        throw usageError(`${input} is not an http(s) URL.`);
+    if (url.username || url.password || url.hash)
+        throw usageError(`${input} must not carry userinfo or a fragment.`);
+    return `${url.origin}${url.pathname}${url.search}`;
+}
+/** The installation vault named `mcp`, created when there is none. */
+async function mcpVault(deps, api) {
+    const { vaults } = await call(deps, api, "GET", "/v1/vaults");
+    const found = vaults.find((vault) => vault.ownerUserId === "installation" && vault.name === MCP_VAULT_NAME);
+    if (found)
+        return found;
+    const key = `nylorun-mcp-${randomUUID()}`;
+    return await call(deps, api, "POST", "/v1/vaults", {
+        requestId: key,
+        idempotencyKey: key,
+        name: MCP_VAULT_NAME,
+        scope: "installation",
+    });
+}
+/** Each credential of the vault bound to `url`, by id, with when it last changed. */
+async function credentialsFor(deps, api, vaultId, url) {
+    const { credentials } = await call(deps, api, "GET", `/v1/vaults/${encodeURIComponent(vaultId)}/credentials`);
+    return new Map(credentials
+        .filter((item) => item.type === "oauth" && item.binding.url === url)
+        .map((item) => [item.id, item.rotatedAt ?? item.createdAt]));
+}
+async function connect(deps, args) {
+    const usage = "nylorun mcp connect <url> --server <name> [--vault <id>] [--client-id <id>] [--tenant <name>] [--no-open]";
+    const flags = parseStackFlags(args, { booleans: ["--no-open"], values: ["--server", "--vault", "--client-id", "--tenant"] }, usage);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${usage}`);
+    const server = flags.values.get("--server");
+    if (!server)
+        throw usageError(`--server names the MCP server, as the agent declares it. Usage: ${usage}`);
+    const url = bindingUrl(flags.rest[0]);
+    const clientId = flags.values.get("--client-id");
+    const name = flags.values.get("--tenant");
+    const api = await runningTenantApi(deps, name === undefined ? {} : { name });
+    const vaultId = flags.values.get("--vault") ?? (await mcpVault(deps, api)).id;
+    const before = await credentialsFor(deps, api, vaultId, url);
+    const started = await call(deps, api, "POST", `/v1/vaults/${encodeURIComponent(vaultId)}/oauth/start`, { url, server, ...(clientId === undefined ? {} : { clientId }) });
+    deps.out(`Sign in to ${server} in your browser:`);
+    deps.out(`  ${started.authorizeUrl}`);
+    if (!flags.booleans.has("--no-open"))
+        await deps.openBrowser(started.authorizeUrl);
+    deps.out("Waiting for the sign-in to finish…");
+    const deadline = Math.min(Date.now() + CONNECT_TIMEOUT_MS, Date.parse(started.expiresAt) || Infinity);
+    const pollMs = deps.pollMs ?? 1000;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        const now = await credentialsFor(deps, api, vaultId, url);
+        for (const [id, changed] of now)
+            if (before.get(id) !== changed) {
+                deps.out(`Connected ${server} (${url}): credential ${id} in installation vault ${vaultId}.`);
+                deps.out(`Sessions use it when they attach the vault: vaultIds: ["${vaultId}"].`);
+                return 0;
+            }
+    }
+    throw new CliError(`The sign-in to ${server} did not finish in time. Run "nylorun mcp connect" again; the browser page says why when the server refused it.`, 1);
+}
+/** `nylorun mcp <connect> ...` */
+export async function mcpCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "connect")
+        return connect(deps, rest);
+    throw usageError(`Usage:\n${mcpUsage}`);
+}

package/dist/stack/operator-keys.d.ts

@@ -0,0 +1,39 @@
+import type { OperatorKey, PutOperatorKeyResponse } from "@nylorun/core/contracts";
+import { type KeyCredentials } from "../project/link.js";
+import type { FetchLike } from "./studio-login.js";
+/** Where a local Tenant's Admin API answers, and its admin key. */
+export interface AdminEndpoint {
+    fetch: FetchLike;
+    adminUrl: string;
+    adminKey: string;
+}
+/** The key `nylorun start` gives the projects it links. */
+export declare const PROJECT_KEY_ID = "project";
+/** The key nylorun commands use outside a linked project. */
+export declare const CLI_KEY_ID = "cli";
+/** Creates key `id` or rotates it; the answer holds the key, this once. */
+export declare function putOperatorKey(admin: AdminEndpoint, id: string): Promise<PutOperatorKeyResponse>;
+export declare function listOperatorKeys(admin: AdminEndpoint): Promise<OperatorKey[]>;
+/** Deletes key `id`: false when there is none. */
+export declare function deleteOperatorKey(admin: AdminEndpoint, id: string): Promise<boolean>;
+/**
+ * Whether `key` reaches the Tenant API at `runtimeUrl`: one authenticated read
+ * (`GET /v1/tenant`). An unknown key is the opaque 404; another answer is an error.
+ */
+export declare function keyAuthenticates(fetch: FetchLike, runtimeUrl: string, key: string): Promise<boolean>;
+/**
+ * The operator key `id` kept in the Host root file `file` (0600): the file's key while it
+ * still authenticates, else `adopt` when it does (a key a project already holds), else a new
+ * key put through the Admin API and written to the file. One process at a time (`lock`), so
+ * concurrent commands share one key instead of rotating each other's.
+ */
+export declare function hostKey(options: {
+    admin: AdminEndpoint;
+    runtimeUrl: string;
+    id: string;
+    file: string;
+    lock: string;
+    adopt?: KeyCredentials;
+}): Promise<KeyCredentials & {
+    put: boolean;
+}>;