nylorun 0.3.0-beta → 0.5.0-beta

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

@@ -1,17 +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 Tenant's Compose file (Runtime Architecture §14.3), written to
+ * `<Host root>/docker/compose.yaml` by `nylorun start`. Each local Tenant is one installation
+ * (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 Tenant'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. Postgres 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 Tenant's state is its 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, with its name (`NYLORUN_TENANT_NAME`) and 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,23 +1,42 @@
 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 Tenant's Compose file (Runtime Architecture §14.3), written to
+ * `<Host root>/docker/compose.yaml` by `nylorun start`. Each local Tenant is one installation
+ * (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 Tenant'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. Postgres 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 Tenant's state is its 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, with its name (`NYLORUN_TENANT_NAME`) and 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
@@ -28,6 +47,7 @@ services:
       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:
@@ -44,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:
@@ -66,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 }
@@ -76,14 +124,24 @@ 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_TENANT_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
+      # Host headers the Runtime accepts: its name on the Compose network, 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.
+      # the Compose 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
@@ -100,12 +158,22 @@ services:
       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 Compose 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, SSE, browsers
       - "127.0.0.1:\${NYLORUN_ADMIN_PORT:?run nylorun start}:4001" # Admin API (operators only)
-    healthcheck:
-      test: ["CMD", "node", "-e", "fetch('http://localhost:4000/ready').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+    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
@@ -124,6 +192,8 @@ services:
       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:-}
+      # Studio's anonymous usage analytics; empty when telemetry is off.
+      NYLORUN_STUDIO_ANALYTICS_ID: \${NYLORUN_STUDIO_ANALYTICS_ID:-}
     volumes:
       - \${NYLORUN_HOST_ROOT}/host-credentials.json:/run/nylorun/host-credentials.json:ro
     ports:

package/dist/stack/docker.js

@@ -45,7 +45,7 @@ export async function checkDocker(docker) {
         return {
             docker: {
                 ok: false,
-                problem: "Docker is required for the Nylorun stack, and the docker command was not found. Install Docker Desktop, OrbStack, Colima or another Docker engine with Compose v2, then retry.",
+                problem: "Docker is required for local Nylorun Tenants, and the docker command was not found. Install Docker Desktop, OrbStack, Colima or another Docker engine with Compose v2, then retry.",
             },
         };
     if (server.code !== 0)

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

@@ -4,8 +4,8 @@
  */
 export declare const DEFAULT_STUDIO_FRAME_ANCESTORS: readonly ["nylorun://localhost", "http://nylorun.localhost"];
 /**
- * Settings in `stack/.env` (mode 0600). Ports and the password persist; the
- * Restate identity public key is derived from `restate-identity.pem`.
+ * 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): the Tenant API. */
@@ -17,7 +17,9 @@ export interface StackEnv {
     /** 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;
@@ -27,8 +29,25 @@ export interface StackEnv {
     studioImage: string;
     /** Exact origins that may frame Studio, separated by spaces (persists). */
     studioFrameAncestors: string;
+    /**
+     * The Google Analytics measurement id Studio reports page views to, or empty
+     * when telemetry is off. Decided again on every start.
+     */
+    studioAnalyticsId: string;
+    /** The Tenant's name, which the Runtime gives the Tenant it creates. */
+    tenantName: 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. */
@@ -38,7 +57,9 @@ export interface PersistedStackEnv {
     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,3 +1,4 @@
+import { DERIVED_PRINCIPAL_ID_PATTERN } from "@nylorun/core/compatibility";
 import { parseFrameAncestors } from "@nylorun/core/contracts";
 import { CliError } from "../errors.js";
 /**
@@ -14,6 +15,7 @@ const KEYS = {
     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",
@@ -21,6 +23,9 @@ const KEYS = {
     runtimeImage: "NYLORUN_RUNTIME_IMAGE",
     studioImage: "NYLORUN_STUDIO_IMAGE",
     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) {
@@ -39,9 +44,9 @@ 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"),
@@ -51,6 +56,10 @@ export function renderEnvFile(env) {
         "",
         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"),
@@ -68,8 +77,32 @@ export function renderEnvFile(env) {
         "# starts; change with nylorun start --studio-embed-origin <origin>.",
         line("studioFrameAncestors"),
         "",
+        "# Studio's anonymous usage analytics; empty when off. Set on every start: turn",
+        "# it off with nylorun telemetry disable or NYLORUN_TELEMETRY_DISABLED=1.",
+        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).",
+        line("tenantName"),
+        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();
@@ -108,13 +141,25 @@ 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 stack/.env: ${error instanceof Error ? error.message : String(error)}`, 1);
+            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

@@ -3,17 +3,17 @@ import type { StackPaths } from "./paths.js";
  * host.json and host-credentials.json (format 1), which `@nylorun/admin`,
  * Studio and the Runtime container all read.
  *
- * For the stack, host.json names the client-facing address: `localhost` and
+ * For a local Tenant, host.json names the client-facing address: `localhost` and
  * the published port. The container binds 0.0.0.0:4000 on its own.
  */
-/** Host name clients use for the stack. Studio's cookie is set on this name too. */
+/** Host name clients use for a local Tenant. Studio's cookie is set on this name too. */
 export declare const STACK_CLIENT_HOST = "localhost";
 export interface HostConfigFile {
     format: 1;
     hostId: string;
     host: string;
     port: number;
-    /** The operator listener's published port (the Admin API); absent on older stacks. */
+    /** The operator listener's published port (the Admin API); absent on older Host roots. */
     adminPort?: number;
     runtimeVersion?: string;
     [field: string]: unknown;
@@ -33,6 +33,15 @@ export declare function writeStackHostConfig(paths: StackPaths, input: {
     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
+ * Host root 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,15 +1,17 @@
 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";
 /**
  * host.json and host-credentials.json (format 1), which `@nylorun/admin`,
  * Studio and the Runtime container all read.
  *
- * For the stack, host.json names the client-facing address: `localhost` and
+ * For a local Tenant, host.json names the client-facing address: `localhost` and
  * the published port. The container binds 0.0.0.0:4000 on its own.
  */
-/** Host name clients use for the stack. Studio's cookie is set on this name too. */
+/** Host name clients use for a local Tenant. Studio's cookie is set on this name too. */
 export const STACK_CLIENT_HOST = "localhost";
 const KNOWN_FORMAT = 1;
 const ADMIN_KEY_PATTERN = /^[0-9a-f]{64}$/;
@@ -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) {
@@ -82,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
+ * Host root 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

@@ -1,5 +1,5 @@
 /**
- * Images the local stack runs. The Runtime and Studio tags are pinned by this
+ * 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.

package/dist/stack/images.js

@@ -1,6 +1,6 @@
 import { pinnedVersion } from "./versions.js";
 /**
- * Images the local stack runs. The Runtime and Studio tags are pinned by this
+ * 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.

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`. */
 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 Tenant's page. */
 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,21 @@ 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_TENANT_NAME",
+    "NYLORUN_DERIVED_PRINCIPALS",
+    "NYLORUN_STUDIO_ANALYTICS_ID",
+];
 /** 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 +75,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`. */
 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 Tenant's page. */
 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. */
+/** Files under the Host root that the nylorun commands read and write. */
 export interface StackPaths {
-    /** The Host root (`~/.nylorun` or `NYLORUN_HOME`), bind-mounted at /nylorun. */
+    /** The Host root (`~/.nylorun/tenants/<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;
+    /** tenant.json: the Tenant'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. */

package/dist/stack/paths.js

@@ -1,18 +1,21 @@
 import { join, resolve } from "node:path";
 export function stackPaths(hostRoot) {
     const root = resolve(hostRoot);
-    const stack = join(root, "stack");
+    const docker = join(root, "docker");
     return {
         root,
         config: join(root, "host.json"),
         credentials: join(root, "host-credentials.json"),
         state: join(root, "host-state.json"),
-        tenants: join(root, "tenants"),
+        record: join(root, "tenant.json"),
+        tenant: join(root, "tenant"),
+        keys: join(root, "keys"),
+        vaultKey: join(root, "keys", "vault-kek"),
         home: join(root, "home"),
         tmp: join(root, "tmp"),
-        stack,
-        compose: join(stack, "compose.yaml"),
-        env: join(stack, ".env"),
-        restateIdentity: join(stack, "restate-identity.pem"),
+        docker,
+        compose: join(docker, "compose.yaml"),
+        env: join(docker, ".env"),
+        restateIdentity: join(docker, "restate-identity.pem"),
     };
 }

package/dist/stack/ports.d.ts

@@ -5,7 +5,7 @@ export declare const DEFAULT_PORTS: {
     readonly studio: 4161;
     readonly restate: 9070;
 };
-/** How the stack finds ports on 127.0.0.1; injectable for tests. */
+/** How `nylorun start` finds ports on 127.0.0.1; injectable for tests. */
 export interface PortProbe {
     isFree(port: number): Promise<boolean>;
     /** A port the OS reports free right now. */
@@ -14,7 +14,7 @@ export interface PortProbe {
 export declare const loopbackPorts: PortProbe;
 /**
  * Choose a port: the persisted one if any (kept even when busy, because the
- * running stack may hold it), else the default when free, else a free one.
+ * running Tenant may hold it), else the default when free, else a free one.
  * Never returns a port in `taken`.
  */
 export declare function choosePort(probe: PortProbe, preferred: number, persisted: number | undefined, taken: ReadonlySet<number>): Promise<number>;