nylorun 0.2.1-beta → 0.4.0-beta

package/dist/stack/compose-file.d.ts

@@ -1,14 +1,36 @@
 /**
- * The local stack's Compose file (Runtime Architecture §14.3), written to
- * `<Host root>/stack/compose.yaml` by `nylorun start`. It is the same for every
- * machine: everything that varies (ports, the Postgres password, UID/GID, the
- * Host root, the Runtime and Studio images) comes from `stack/.env`.
+ * A local stack's Compose file (Runtime Architecture §14.3), written to
+ * `<Host root>/docker/compose.yaml` by `nylorun start`. Each stack is one installation with
+ * one Tenant (tenancy.md §6): its own Compose project (`nylorun-<name>`, the file's `name`),
+ * volumes, network and ports. Everything else that varies (ports, the Postgres password,
+ * UID/GID, the Host root, the images, the stack's name) comes from `docker/.env`.
  *
- * Tenants are Postgres schemas, executed through Restate, with their history in
- * s2-lite; the Runtime's /ready checks all three.
+ * The Tenant's state is the stack's Postgres database, executed through Restate, with its
+ * history in s2-lite; the Runtime's /ready checks all three. Postgres initialises the
+ * database with C collation (`--locale=C`) and runs with `wal_level=logical`: the stream
+ * relay feeds s2-lite from the record over logical replication (Durable Streams), and
+ * `max_slot_wal_keep_size` caps the WAL a stuck relay can hold. The Runtime creates the
+ * Tenant on its first start, named after the stack (`NYLORUN_TENANT_NAME`), with the derived
+ * principals of `NYLORUN_DERIVED_PRINCIPALS` (`project` for the Project link).
  *
  * Restate signs requests to the Worker endpoint with the private key in
- * `stack/restate-identity.pem`, mounted read-only; the Runtime gets the public
+ * `docker/restate-identity.pem`, mounted read-only; the Runtime gets the public
  * key as NYLORUN_RESTATE_IDENTITY_KEY.
+ *
+ * The combined packing (blueprint D12): the `runtime` container runs the core
+ * and loop services, and the `gateway` container runs gates: the Model Gate,
+ * which alone reads model credentials, and the Tool Gate (F4.1), which alone
+ * holds remote MCP connections and their credentials and POSTs every Action
+ * delivery. Every model call, remote MCP call and delivery of the loop crosses it
+ * (NYLORUN_GATES_URL, with NYLORUN_GATES_TOKEN from `.env`); stdio MCP servers
+ * still run in the runtime container. The gateway also runs keys (F4.2): the only
+ * holder of the vault key, it runs every vault write that touches a secret and signs
+ * every token (NYLORUN_KEYS_URL). The gateway mounts only the Host's Tenant directory
+ * (`tenant/`) and its keys directory (`keys/`, the vault key), read-only: never
+ * host-credentials.json. The runtime mounts the Host root with `keys/` and `docker/`
+ * covered by empty read-only mounts, so it can read neither the vault key nor
+ * Restate's private key and `.env`. The runtime does not wait for the gateway: while
+ * it is down, model and MCP calls fail, deliveries are retried, vault writes and
+ * token minting answer 503, and the session takes the next message.
  */
-export declare function renderComposeFile(): string;
+export declare function renderComposeFile(project: string): string;

package/dist/stack/compose-file.js

@@ -1,28 +1,53 @@
 import { PINNED_IMAGES } from "./images.js";
 /**
- * The local stack's Compose file (Runtime Architecture §14.3), written to
- * `<Host root>/stack/compose.yaml` by `nylorun start`. It is the same for every
- * machine: everything that varies (ports, the Postgres password, UID/GID, the
- * Host root, the Runtime and Studio images) comes from `stack/.env`.
+ * A local stack's Compose file (Runtime Architecture §14.3), written to
+ * `<Host root>/docker/compose.yaml` by `nylorun start`. Each stack is one installation with
+ * one Tenant (tenancy.md §6): its own Compose project (`nylorun-<name>`, the file's `name`),
+ * volumes, network and ports. Everything else that varies (ports, the Postgres password,
+ * UID/GID, the Host root, the images, the stack's name) comes from `docker/.env`.
  *
- * Tenants are Postgres schemas, executed through Restate, with their history in
- * s2-lite; the Runtime's /ready checks all three.
+ * The Tenant's state is the stack's Postgres database, executed through Restate, with its
+ * history in s2-lite; the Runtime's /ready checks all three. Postgres initialises the
+ * database with C collation (`--locale=C`) and runs with `wal_level=logical`: the stream
+ * relay feeds s2-lite from the record over logical replication (Durable Streams), and
+ * `max_slot_wal_keep_size` caps the WAL a stuck relay can hold. The Runtime creates the
+ * Tenant on its first start, named after the stack (`NYLORUN_TENANT_NAME`), with the derived
+ * principals of `NYLORUN_DERIVED_PRINCIPALS` (`project` for the Project link).
  *
  * Restate signs requests to the Worker endpoint with the private key in
- * `stack/restate-identity.pem`, mounted read-only; the Runtime gets the public
+ * `docker/restate-identity.pem`, mounted read-only; the Runtime gets the public
  * key as NYLORUN_RESTATE_IDENTITY_KEY.
+ *
+ * The combined packing (blueprint D12): the `runtime` container runs the core
+ * and loop services, and the `gateway` container runs gates: the Model Gate,
+ * which alone reads model credentials, and the Tool Gate (F4.1), which alone
+ * holds remote MCP connections and their credentials and POSTs every Action
+ * delivery. Every model call, remote MCP call and delivery of the loop crosses it
+ * (NYLORUN_GATES_URL, with NYLORUN_GATES_TOKEN from `.env`); stdio MCP servers
+ * still run in the runtime container. The gateway also runs keys (F4.2): the only
+ * holder of the vault key, it runs every vault write that touches a secret and signs
+ * every token (NYLORUN_KEYS_URL). The gateway mounts only the Host's Tenant directory
+ * (`tenant/`) and its keys directory (`keys/`, the vault key), read-only: never
+ * host-credentials.json. The runtime mounts the Host root with `keys/` and `docker/`
+ * covered by empty read-only mounts, so it can read neither the vault key nor
+ * Restate's private key and `.env`. The runtime does not wait for the gateway: while
+ * it is down, model and MCP calls fail, deliveries are retried, vault writes and
+ * token minting answer 503, and the session takes the next message.
  */
-export function renderComposeFile() {
+export function renderComposeFile(project) {
     return `# Written by \`nylorun start\`; rewritten on every start. Settings live in .env.
-name: nylorun
+name: ${project}
 
 services:
   postgres: # Session Store
     image: ${PINNED_IMAGES.postgres}
+    # Logical replication feeds the stream relay; a stuck slot is capped at 4 GB of WAL.
+    command: ["postgres", "-c", "wal_level=logical", "-c", "max_slot_wal_keep_size=4GB"]
     environment:
       POSTGRES_USER: nylorun
       POSTGRES_PASSWORD: \${NYLORUN_POSTGRES_PASSWORD:?run nylorun start}
       POSTGRES_DB: nylorun
+      POSTGRES_INITDB_ARGS: "--locale=C" # C collation for the whole database
     volumes:
       - postgres:/var/lib/postgresql/data
     healthcheck:
@@ -39,7 +64,7 @@ services:
       RESTATE_WORKER__INVOKER__REQUEST_IDENTITY_PRIVATE_KEY_PEM_FILE: /run/nylorun/restate-identity.pem
     volumes:
       - restate:/restate-data
-      - \${NYLORUN_HOST_ROOT:?run nylorun start}/stack/restate-identity.pem:/run/nylorun/restate-identity.pem:ro
+      - \${NYLORUN_HOST_ROOT:?run nylorun start}/docker/restate-identity.pem:/run/nylorun/restate-identity.pem:ro
     ports:
       - "127.0.0.1:\${NYLORUN_RESTATE_PORT:?run nylorun start}:9070" # Restate UI and admin, for debugging
     healthcheck:
@@ -61,9 +86,37 @@ services:
     # the Runtime's /ready covers it.
     restart: unless-stopped
 
+  gateway: # the Model and Tool Gates and keys: the vault key, credentials, signing, outbound calls; not published
+    image: \${NYLORUN_RUNTIME_IMAGE:?run nylorun start}
+    command: ["--service", "gates,keys"]
+    user: "\${NYLORUN_UID:?run nylorun start}:\${NYLORUN_GID:?run nylorun start}"
+    depends_on:
+      postgres: { condition: service_healthy }
+    environment:
+      NYLORUN_HOME: /nylorun
+      NYLORUN_PACKING: combined
+      NYLORUN_GATES_LISTEN_PORT: "4100"
+      NYLORUN_GATES_ALLOWED_HOSTS: gateway:4100
+      NYLORUN_GATES_TOKEN: \${NYLORUN_GATES_TOKEN:?run nylorun start}
+      NYLORUN_DATABASE_URL: postgres://nylorun:\${NYLORUN_POSTGRES_PASSWORD}@postgres:5432/nylorun
+      # Action endpoints on this machine: \`localhost\` in a registered URL means the Docker host.
+      NYLORUN_ENDPOINT_LOOPBACK: docker-host
+    extra_hosts:
+      host.docker.internal: host-gateway # model servers, MCP servers and Action endpoints on this machine
+    volumes:
+      # The Tenant's homes and its vault key only, read-only.
+      - \${NYLORUN_HOST_ROOT:?run nylorun start}/tenant:/nylorun/tenant:ro
+      - \${NYLORUN_HOST_ROOT:?run nylorun start}/keys:/nylorun/keys:ro
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://localhost:4100/ready').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+      interval: 2s
+      timeout: 5s
+      retries: 60
+    restart: unless-stopped
+
   runtime:
     image: \${NYLORUN_RUNTIME_IMAGE:?run nylorun start}
-    command: ["--role", "all"]
+    command: ["--service", "core,loop"]
     user: "\${NYLORUN_UID:?run nylorun start}:\${NYLORUN_GID:?run nylorun start}"
     depends_on:
       postgres: { condition: service_healthy }
@@ -71,12 +124,26 @@ services:
       s2: { condition: service_started }
     environment:
       NYLORUN_HOME: /nylorun
+      NYLORUN_PACKING: combined
+      # The Tenant the Runtime creates on its first start (later starts open it).
+      NYLORUN_TENANT_NAME: \${NYLORUN_STACK_NAME:?run nylorun start}
+      NYLORUN_DERIVED_PRINCIPALS: \${NYLORUN_DERIVED_PRINCIPALS:-project}
+      # Model calls, remote MCP calls and deliveries go through the gateway, and vault writes
+      # and token signing through its keys service: this container never reads a credential
+      # or the vault key.
+      NYLORUN_GATES_URL: http://gateway:4100
+      NYLORUN_KEYS_URL: http://gateway:4100
+      NYLORUN_GATES_TOKEN: \${NYLORUN_GATES_TOKEN:?run nylorun start}
       NYLORUN_LISTEN_HOST: 0.0.0.0
       NYLORUN_LISTEN_PORT: "4000"
       # Host headers the Runtime accepts: the stack network name, and the
       # published port as clients on this machine address it.
       NYLORUN_ALLOWED_HOSTS: runtime:4000,localhost:\${NYLORUN_PORT},127.0.0.1:\${NYLORUN_PORT}
       NYLORUN_PUBLIC_URL: http://localhost:\${NYLORUN_PORT} # reported by /v1/admin/status
+      # The Admin API on its own listener, published on loopback only; Studio reaches it on
+      # the stack network. Port 4000 serves the Tenant API alone.
+      NYLORUN_ADMIN_LISTEN_PORT: "4001"
+      NYLORUN_ADMIN_ALLOWED_HOSTS: runtime:4001,localhost:\${NYLORUN_ADMIN_PORT},127.0.0.1:\${NYLORUN_ADMIN_PORT}
       NYLORUN_DATABASE_URL: postgres://nylorun:\${NYLORUN_POSTGRES_PASSWORD}@postgres:5432/nylorun
       NYLORUN_RESTATE_INGRESS_URL: http://restate:8080
       NYLORUN_RESTATE_ADMIN_URL: http://restate:9070
@@ -85,13 +152,28 @@ services:
       NYLORUN_S2_ENDPOINT: http://s2:80
       NYLORUN_S2_TOKEN: ignored # s2-lite has no access tokens yet
       NYLORUN_WORKSPACE_STORE_URL: file:///workspaces
+      # Action endpoints on this machine: \`localhost\` in a registered URL means the Docker host.
+      NYLORUN_ENDPOINT_LOOPBACK: docker-host
+    extra_hosts:
+      host.docker.internal: host-gateway # the Docker host, also on Linux Docker Engine
     volumes:
       - \${NYLORUN_HOST_ROOT:?run nylorun start}:/nylorun # Host root
+      # Empty and read-only over the vault key (keys/) and the stack's secrets (docker/):
+      # only the gateway reads the key, and only Restate its private key.
+      - type: tmpfs
+        target: /nylorun/keys
+        read_only: true
+        tmpfs: { size: 4096, mode: 0755 } # empty, and listable by the runtime user
+      - type: tmpfs
+        target: /nylorun/docker
+        read_only: true
+        tmpfs: { size: 4096, mode: 0755 } # empty, and listable by the runtime user
       - workspaces:/workspaces
     ports:
-      - "127.0.0.1:\${NYLORUN_PORT:?run nylorun start}:4000" # Tenant API, Admin API, SSE
-    healthcheck:
-      test: ["CMD", "node", "-e", "fetch('http://localhost:4000/ready').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+      - "127.0.0.1:\${NYLORUN_PORT:?run nylorun start}:4000" # Tenant API, SSE, browsers
+      - "127.0.0.1:\${NYLORUN_ADMIN_PORT:?run nylorun start}:4001" # Admin API (operators only)
+    healthcheck: # liveness: a Tenant that cannot open is reported by nylorun start from the Admin status, not by a 300 s wait
+      test: ["CMD", "node", "-e", "fetch('http://localhost:4000/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
       interval: 2s
       timeout: 5s
       retries: 60
@@ -103,11 +185,13 @@ services:
     depends_on:
       runtime: { condition: service_healthy }
     environment:
-      NYLORUN_RUNTIME_URL: http://runtime:4000
+      NYLORUN_RUNTIME_URL: http://runtime:4001 # the operator listener: Admin and Tenant API
       NYLORUN_ADMIN_KEY_FILE: /run/nylorun/host-credentials.json
       PORT: "3000"
       # Studio's Host check accepts localhost/127.0.0.1 on the published port.
       NYLORUN_STUDIO_PUBLIC_PORT: \${NYLORUN_STUDIO_PORT}
+      # Exact origins that may frame Studio (Babai Desktop); kept in .env.
+      NYLORUN_STUDIO_FRAME_ANCESTORS: \${NYLORUN_STUDIO_FRAME_ANCESTORS:-}
     volumes:
       - \${NYLORUN_HOST_ROOT}/host-credentials.json:/run/nylorun/host-credentials.json:ro
     ports:

package/dist/stack/env-file.d.ts

@@ -1,16 +1,25 @@
 /**
- * Settings in `stack/.env` (mode 0600). Ports and the password persist; the
- * Restate identity public key is derived from `restate-identity.pem`.
+ * 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).
+ */
+export declare const DEFAULT_STUDIO_FRAME_ANCESTORS: readonly ["nylorun://localhost", "http://nylorun.localhost"];
+/**
+ * Settings in `docker/.env` (mode 0600). Ports, the password and the gates token
+ * persist; the Restate identity public key is derived from `restate-identity.pem`.
  */
 export interface StackEnv {
-    /** Published Runtime port (loopback). */
+    /** Published Runtime port (loopback): the Tenant API. */
     runtimePort: number;
+    /** Published operator port (loopback): the Admin API. */
+    adminPort: number;
     /** Published Studio port (loopback). */
     studioPort: number;
     /** Published Restate UI and admin port (loopback). */
     restatePort: number;
     postgresPassword: string;
-    /** `publickeyv1_...` of `stack/restate-identity.pem`. */
+    /** The token the runtime presents to the gateway (`NYLORUN_GATES_TOKEN`), 32 bytes as hex. */
+    gatesToken: string;
+    /** `publickeyv1_...` of `docker/restate-identity.pem`. */
     restateIdentityKey: string;
     uid: number;
     gid: number;
@@ -18,15 +27,34 @@ export interface StackEnv {
     hostRoot: string;
     runtimeImage: string;
     studioImage: string;
+    /** Exact origins that may frame Studio, separated by spaces (persists). */
+    studioFrameAncestors: string;
+    /** The stack's name: the name of the Tenant its Runtime creates. */
+    stackName: string;
+    /**
+     * Derived principals the Runtime registers on its Tenant, comma-separated (persists);
+     * always includes `project`, the Project link's principal.
+     */
+    derivedPrincipals: string;
 }
 export declare function renderEnvFile(env: StackEnv): string;
+/**
+ * `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 declare function parseDerivedPrincipals(raw: string, source: string): string[];
 /** Parse KEY=value lines; comments and blank lines are skipped. */
 export declare function parseEnvLines(text: string): Map<string, string>;
 /** The settings that persist across starts, from an existing .env. */
 export interface PersistedStackEnv {
     runtimePort?: number;
+    adminPort?: number;
     studioPort?: number;
     restatePort?: number;
     postgresPassword?: string;
+    gatesToken?: string;
+    /** Validated origins; absent when the line is missing (an older .env). */
+    studioFrameAncestors?: string[];
+    derivedPrincipals?: string[];
 }
 export declare function parsePersisted(text: string): PersistedStackEnv;

package/dist/stack/env-file.js

@@ -1,15 +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).
+ */
+export const DEFAULT_STUDIO_FRAME_ANCESTORS = [
+    "nylorun://localhost",
+    "http://nylorun.localhost",
+];
 const KEYS = {
     runtimePort: "NYLORUN_PORT",
+    adminPort: "NYLORUN_ADMIN_PORT",
     studioPort: "NYLORUN_STUDIO_PORT",
     restatePort: "NYLORUN_RESTATE_PORT",
     postgresPassword: "NYLORUN_POSTGRES_PASSWORD",
+    gatesToken: "NYLORUN_GATES_TOKEN",
     restateIdentityKey: "NYLORUN_RESTATE_IDENTITY_KEY",
     uid: "NYLORUN_UID",
     gid: "NYLORUN_GID",
     hostRoot: "NYLORUN_HOST_ROOT",
     runtimeImage: "NYLORUN_RUNTIME_IMAGE",
     studioImage: "NYLORUN_STUDIO_IMAGE",
+    studioFrameAncestors: "NYLORUN_STUDIO_FRAME_ANCESTORS",
+    stackName: "NYLORUN_STACK_NAME",
+    derivedPrincipals: "NYLORUN_DERIVED_PRINCIPALS",
 };
 /** Compose .env values: single quotes keep a value literal (no interpolation). */
 function quote(key, value) {
@@ -28,17 +43,22 @@ function unquote(value) {
 export function renderEnvFile(env) {
     const line = (field) => `${KEYS[field]}=${quote(KEYS[field], String(env[field]))}`;
     return [
-        "# Written by `nylorun start`. Mode 0600: holds the Postgres password.",
-        "# Ports and the password 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 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.",
         "",
         "# Published on 127.0.0.1; clients use http://localhost:<port>.",
         line("runtimePort"),
+        line("adminPort"),
         line("studioPort"),
         line("restatePort"),
         "",
         line("postgresPassword"),
         "",
+        "# The runtime presents this token to the gateway (the Model Gate) with every",
+        "# model call.",
+        line("gatesToken"),
+        "",
         "# 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"),
@@ -52,8 +72,32 @@ 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>.",
+        line("studioFrameAncestors"),
+        "",
+        "# The stack's name, which its 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).",
+        line("stackName"),
+        line("derivedPrincipals"),
+        "",
     ].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();
@@ -80,6 +124,9 @@ export function parsePersisted(text) {
     const runtimePort = port(values.get(KEYS.runtimePort));
     if (runtimePort)
         out.runtimePort = runtimePort;
+    const adminPort = port(values.get(KEYS.adminPort));
+    if (adminPort)
+        out.adminPort = adminPort;
     const studioPort = port(values.get(KEYS.studioPort));
     if (studioPort)
         out.studioPort = studioPort;
@@ -89,5 +136,26 @@ export function parsePersisted(text) {
     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 ancestors = values.get(KEYS.studioFrameAncestors);
+    if (ancestors !== undefined) {
+        try {
+            out.studioFrameAncestors = parseFrameAncestors(ancestors);
+        }
+        catch (error) {
+            throw new CliError(`${KEYS.studioFrameAncestors} in docker/.env: ${error instanceof Error ? error.message : String(error)}`, 1);
+        }
+    }
     return out;
 }

package/dist/stack/host-files.d.ts

@@ -13,6 +13,8 @@ export interface HostConfigFile {
     hostId: string;
     host: string;
     port: number;
+    /** The operator listener's published port (the Admin API); absent on older stacks. */
+    adminPort?: number;
     runtimeVersion?: string;
     [field: string]: unknown;
 }
@@ -21,14 +23,25 @@ export declare function newHostId(): string;
 export declare function ensureHostLayout(paths: StackPaths): Promise<void>;
 export declare function readHostConfig(paths: StackPaths): Promise<Record<string, unknown> | undefined>;
 /**
- * Write host.json with the published port. Keeps the hostId and unknown fields
- * of an existing file; refuses a newer format.
+ * Write host.json with the published port and the Runtime version that runs
+ * the Host. Keeps the hostId and unknown fields of an existing file, and its
+ * runtimeVersion when `runtimeVersion` is undefined; refuses a newer format.
  */
 export declare function writeStackHostConfig(paths: StackPaths, input: {
     port: number;
-    runtimeVersion: string;
+    adminPort?: number;
+    runtimeVersion: string | undefined;
 }): Promise<HostConfigFile>;
 export declare function readAdminKey(paths: StackPaths): Promise<string | undefined>;
+/**
+ * The Tenant's vault key in `keys/vault-kek` (32 random bytes, base64, mode 0600), which only the
+ * gateway container mounts (F4.2): created if missing, or moved from `tenant/vault-kek`, where a
+ * stack before F4.2 kept it. The gateway never creates it.
+ */
+export declare function ensureVaultKey(paths: StackPaths): Promise<{
+    created: boolean;
+    moved: boolean;
+}>;
 /** Create host-credentials.json (mode 0600) if missing; always leave it 0600. */
 export declare function ensureHostCredentials(paths: StackPaths): Promise<{
     adminKey: string;

package/dist/stack/host-files.js

@@ -1,5 +1,7 @@
 import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
 import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { newTenantId } from "@nylorun/core/compatibility";
 import { CliError } from "../errors.js";
 /**
@@ -24,7 +26,7 @@ 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.tenants, paths.stack])
+    for (const dir of [paths.root, paths.home, paths.tmp, paths.tenant, paths.keys, paths.docker])
         await mkdir(dir, { recursive: true, mode: 0o700 });
 }
 export async function readHostConfig(paths) {
@@ -46,8 +48,9 @@ export async function readHostConfig(paths) {
     }
 }
 /**
- * Write host.json with the published port. Keeps the hostId and unknown fields
- * of an existing file; refuses a newer format.
+ * Write host.json with the published port and the Runtime version that runs
+ * the Host. Keeps the hostId and unknown fields of an existing file, and its
+ * runtimeVersion when `runtimeVersion` is undefined; refuses a newer format.
  */
 export async function writeStackHostConfig(paths, input) {
     const existing = (await readHostConfig(paths)) ?? {};
@@ -64,7 +67,8 @@ export async function writeStackHostConfig(paths, input) {
         hostId,
         host: STACK_CLIENT_HOST,
         port: input.port,
-        runtimeVersion: input.runtimeVersion,
+        ...(input.adminPort === undefined ? {} : { adminPort: input.adminPort }),
+        ...(input.runtimeVersion !== undefined ? { runtimeVersion: input.runtimeVersion } : {}),
     };
     await writeAtomic(paths.config, `${JSON.stringify(config, null, 2)}\n`);
     return config;
@@ -80,6 +84,27 @@ export async function readAdminKey(paths) {
         return undefined;
     }
 }
+/**
+ * The Tenant's vault key in `keys/vault-kek` (32 random bytes, base64, mode 0600), which only the
+ * gateway container mounts (F4.2): created if missing, or moved from `tenant/vault-kek`, where a
+ * stack before F4.2 kept it. The gateway never creates it.
+ */
+export async function ensureVaultKey(paths) {
+    await mkdir(paths.keys, { recursive: true, mode: 0o700 });
+    await chmod(paths.keys, 0o700);
+    if (existsSync(paths.vaultKey)) {
+        await chmod(paths.vaultKey, 0o600);
+        return { created: false, moved: false };
+    }
+    const legacy = join(paths.tenant, "vault-kek");
+    if (existsSync(legacy)) {
+        await rename(legacy, paths.vaultKey);
+        await chmod(paths.vaultKey, 0o600);
+        return { created: false, moved: true };
+    }
+    await writeAtomic(paths.vaultKey, `${randomBytes(32).toString("base64")}\n`);
+    return { created: true, moved: false };
+}
 /** Create host-credentials.json (mode 0600) if missing; always leave it 0600. */
 export async function ensureHostCredentials(paths) {
     const existing = await readAdminKey(paths);

package/dist/stack/images.d.ts

@@ -16,6 +16,8 @@ export interface StackImages {
     restate: string;
     s2: 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;
 export declare function stackImages(env: Readonly<Record<string, string | undefined>>, versions?: {
     runtime: string;
     studio: string;

package/dist/stack/images.js

@@ -10,18 +10,22 @@ export const PINNED_IMAGES = {
     restate: "docker.restate.dev/restatedev/restate:1.7.12",
     s2: "ghcr.io/s2-streamstore/s2:0.43.0",
 };
+function override(env, name) {
+    const value = env[name]?.trim();
+    return value ? value : undefined;
+}
+/** `NYLORUN_RUNTIME_IMAGE` names the Runtime image, so its version is unknown here. */
+export function runtimeImageOverridden(env) {
+    return override(env, "NYLORUN_RUNTIME_IMAGE") !== undefined;
+}
 export function stackImages(env, versions = {
     runtime: pinnedVersion("runtime"),
     studio: pinnedVersion("studio"),
 }) {
-    const override = (name) => {
-        const value = env[name]?.trim();
-        return value ? value : undefined;
-    };
     return {
-        runtime: override("NYLORUN_RUNTIME_IMAGE") ??
+        runtime: override(env, "NYLORUN_RUNTIME_IMAGE") ??
             `ghcr.io/nylorun/runtime:${versions.runtime}`,
-        studio: override("NYLORUN_STUDIO_IMAGE") ??
+        studio: override(env, "NYLORUN_STUDIO_IMAGE") ??
             `ghcr.io/nylorun/studio:${versions.studio}`,
         ...PINNED_IMAGES,
     };

package/dist/stack/index.d.ts

@@ -1,13 +1,13 @@
 import { type StackDeps } from "./commands.js";
 export { ensureStack, isStackCommand, readStackStatus, stackUsage, studioLoginUrl, tenantStudioPath, STACK_SERVICES, } from "./commands.js";
-export type { StackDeps, StackEndpoints, StackStatus } from "./commands.js";
+export type { StackDeps, StackEndpoints, StackStatus, StackTenant } from "./commands.js";
 export { checkDocker } from "./docker.js";
 export type { Check, DockerChecks } from "./docker.js";
 /** Real dependencies: docker on PATH, global fetch, the terminal. */
 export declare function defaultStackDeps(env: Readonly<Record<string, string | undefined>>): StackDeps;
-/** Entry for `nylorun start|stop|status|logs|reset|studio`. */
+/** Entry for `nylorun start|stop|status|logs|reset|studio|ls|delete|legacy`. */
 export declare function stackCommand(name: string, args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
-/** `nylorun studio`, landing on `next` (a Tenant page) when given. */
+/** `nylorun studio`, landing on `next` when given, else on the stack's Tenant. */
 export declare function studioCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>, options?: {
     next?: string;
 }): Promise<number>;

package/dist/stack/index.js

@@ -13,12 +13,17 @@ function browserCommand(env) {
         return "wslview";
     return "xdg-open";
 }
+/**
+ * Variables `docker/.env` sets for Compose: `nylorun start` writes them there, so the
+ * environment must not override them when Compose interpolates the file.
+ */
+const STACK_ENV_OWNED = ["NYLORUN_STACK_NAME", "NYLORUN_DERIVED_PRINCIPALS"];
 /** Real dependencies: docker on PATH, global fetch, the terminal. */
 export function defaultStackDeps(env) {
     const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
     return {
         env,
-        docker: spawnDocker(env),
+        docker: spawnDocker(Object.fromEntries(Object.entries(env).filter(([key]) => !STACK_ENV_OWNED.includes(key)))),
         fetch: (input, init) => fetch(input, init),
         ports: loopbackPorts,
         uid: typeof process.getuid === "function" ? process.getuid() : 1000,
@@ -66,11 +71,11 @@ export function defaultStackDeps(env) {
         },
     };
 }
-/** Entry for `nylorun start|stop|status|logs|reset|studio`. */
+/** Entry for `nylorun start|stop|status|logs|reset|studio|ls|delete|legacy`. */
 export async function stackCommand(name, args, env) {
     return await runStackCommand(name, args, defaultStackDeps(env));
 }
-/** `nylorun studio`, landing on `next` (a Tenant page) when given. */
+/** `nylorun studio`, landing on `next` when given, else on the stack's Tenant. */
 export async function studioCommand(args, env, options = {}) {
     return await runStudioCommand(args, defaultStackDeps(env), options);
 }

package/dist/stack/paths.d.ts

@@ -1,6 +1,6 @@
 /** Files under the Host root that the stack commands read and write. */
 export interface StackPaths {
-    /** The Host root (`~/.nylorun` or `NYLORUN_HOME`), bind-mounted at /nylorun. */
+    /** The Host root (`~/.nylorun/stacks/<name>` or `NYLORUN_HOME`), bind-mounted at /nylorun. */
     root: string;
     /** host.json: client-facing host and published port, no secrets. */
     config: string;
@@ -8,10 +8,18 @@ export interface StackPaths {
     credentials: string;
     /** host-state.json: written only by a launcher-managed Runtime. */
     state: string;
-    tenants: string;
+    /** stack.json: the stack's name and the project it was created for. */
+    record: string;
+    /** The Tenant directory: homes, sandboxes, plugin data, logs. */
+    tenant: string;
+    /** The keys directory, mounted only into the gateway (F4.2). */
+    keys: string;
+    /** The Tenant's vault key (KEK), `keys/vault-kek`. */
+    vaultKey: string;
     home: string;
     tmp: string;
-    stack: string;
+    /** The Docker Compose files: compose.yaml, .env and the Restate identity key. */
+    docker: string;
     compose: string;
     env: string;
     /** Restate's request-identity private key (Ed25519 PKCS#8 PEM), mode 0600. */