nylorun 0.3.0-beta → 0.4.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 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. 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 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,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 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. 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 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
@@ -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,6 +124,16 @@ 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
@@ -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 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, 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

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,20 @@ export interface StackEnv {
     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. */
@@ -38,7 +52,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,8 @@ const KEYS = {
     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) {
@@ -39,9 +43,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 +55,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 +76,28 @@ export function renderEnvFile(env) {
         "# 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();
@@ -108,13 +136,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

@@ -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
+ * 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) {
@@ -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
+ * 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/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. */

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, "stack.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/prepare.d.ts

@@ -11,21 +11,28 @@ export interface PreparedStack {
     firstRun: boolean;
 }
 /** Read the persisted stack settings without writing anything. */
-export declare function readStackEnv(paths: StackPaths): Promise<import("./env-file.js").PersistedStackEnv | undefined>;
+export declare function readStackEnv(paths: Pick<StackPaths, "env">): Promise<import("./env-file.js").PersistedStackEnv | undefined>;
 /**
  * Write everything `docker compose up` needs under the Host root:
- * host.json, host-credentials.json (0600), stack/compose.yaml,
- * stack/.env (0600) and stack/restate-identity.pem (0600). Ports and the
+ * host.json, host-credentials.json (0600), docker/compose.yaml,
+ * docker/.env (0600) and docker/restate-identity.pem (0600). Ports and the
  * Postgres password persist in .env; the identity key persists in its PEM.
  */
 export declare function prepareStack(input: {
     paths: StackPaths;
+    /** The stack's name (its Tenant's name) and its Compose project. */
+    name: string;
+    project: string;
     images: StackImages;
     uid: number;
     gid: number;
     /** Recorded in host.json; undefined keeps the recorded version. */
     runtimeVersion: string | undefined;
     ports: PortProbe;
+    /** Ports other stacks keep in their `.env`: never chosen for a port not chosen yet. */
+    reserved?: ReadonlySet<number>;
+    /** `NYLORUN_DERIVED_PRINCIPALS` from the environment of `nylorun start`; else kept. */
+    derivedPrincipals?: string;
     /**
      * Changes to the origins that may embed Studio: `reset` goes back to the
      * defaults, `add` appends (for example a desktop app's dev server).

package/dist/stack/prepare.js

@@ -3,8 +3,8 @@ import { chmod, readFile, rename, writeFile } from "node:fs/promises";
 import { renderComposeFile } from "./compose-file.js";
 import { parseFrameAncestors } from "@nylorun/core/contracts";
 import { CliError } from "../errors.js";
-import { DEFAULT_STUDIO_FRAME_ANCESTORS, parsePersisted, renderEnvFile, } from "./env-file.js";
-import { ensureHostCredentials, ensureHostLayout, writeStackHostConfig, } from "./host-files.js";
+import { DEFAULT_STUDIO_FRAME_ANCESTORS, parseDerivedPrincipals, parsePersisted, renderEnvFile, } from "./env-file.js";
+import { ensureHostCredentials, ensureVaultKey, ensureHostLayout, writeStackHostConfig, } from "./host-files.js";
 import { choosePort, DEFAULT_PORTS } from "./ports.js";
 import { ensureIdentityKey } from "./restate-identity.js";
 async function writeFileMode(path, text, mode) {
@@ -28,8 +28,8 @@ export async function readStackEnv(paths) {
 }
 /**
  * Write everything `docker compose up` needs under the Host root:
- * host.json, host-credentials.json (0600), stack/compose.yaml,
- * stack/.env (0600) and stack/restate-identity.pem (0600). Ports and the
+ * host.json, host-credentials.json (0600), docker/compose.yaml,
+ * docker/.env (0600) and docker/restate-identity.pem (0600). Ports and the
  * Postgres password persist in .env; the identity key persists in its PEM.
  */
 export async function prepareStack(input) {
@@ -38,13 +38,17 @@ export async function prepareStack(input) {
     const persisted = (await readStackEnv(paths)) ?? {};
     const firstRun = persisted.runtimePort === undefined;
     const taken = new Set();
-    const runtimePort = await choosePort(input.ports, DEFAULT_PORTS.runtime, persisted.runtimePort, taken);
-    taken.add(runtimePort);
-    const adminPort = await choosePort(input.ports, DEFAULT_PORTS.admin, persisted.adminPort, taken);
-    taken.add(adminPort);
-    const studioPort = await choosePort(input.ports, DEFAULT_PORTS.studio, persisted.studioPort, taken);
-    taken.add(studioPort);
-    const restatePort = await choosePort(input.ports, DEFAULT_PORTS.restate, persisted.restatePort, taken);
+    const reserved = input.reserved ?? new Set();
+    const pick = async (preferred, persistedPort) => {
+        const avoid = persistedPort === undefined ? new Set([...taken, ...reserved]) : taken;
+        const port = await choosePort(input.ports, preferred, persistedPort, avoid);
+        taken.add(port);
+        return port;
+    };
+    const runtimePort = await pick(DEFAULT_PORTS.runtime, persisted.runtimePort);
+    const adminPort = await pick(DEFAULT_PORTS.admin, persisted.adminPort);
+    const studioPort = await pick(DEFAULT_PORTS.studio, persisted.studioPort);
+    const restatePort = await pick(DEFAULT_PORTS.restate, persisted.restatePort);
     const identity = await ensureIdentityKey(paths.restateIdentity, writeFileMode);
     let added;
     try {
@@ -63,6 +67,8 @@ export async function prepareStack(input) {
         studioPort,
         restatePort,
         postgresPassword: persisted.postgresPassword ?? randomBytes(24).toString("hex"),
+        // Kept across starts: a new token would recreate the runtime and gateway containers.
+        gatesToken: persisted.gatesToken ?? randomBytes(32).toString("hex"),
         restateIdentityKey: identity.publicKey,
         uid: input.uid,
         gid: input.gid,
@@ -70,14 +76,19 @@ export async function prepareStack(input) {
         runtimeImage: input.images.runtime,
         studioImage: input.images.studio,
         studioFrameAncestors,
+        stackName: input.name,
+        derivedPrincipals: (input.derivedPrincipals?.trim()
+            ? parseDerivedPrincipals(input.derivedPrincipals, "NYLORUN_DERIVED_PRINCIPALS")
+            : (persisted.derivedPrincipals ?? ["project"])).join(","),
     };
     const { adminKey } = await ensureHostCredentials(paths);
+    await ensureVaultKey(paths);
     const host = await writeStackHostConfig(paths, {
         port: runtimePort,
         adminPort,
         runtimeVersion: input.runtimeVersion,
     });
     await writeFileMode(paths.env, renderEnvFile(env), 0o600);
-    await writeFileMode(paths.compose, renderComposeFile(), 0o644);
+    await writeFileMode(paths.compose, renderComposeFile(input.project), 0o644);
     return { env, host, adminKey, firstRun };
 }

package/dist/stack/restate-identity.d.ts

@@ -3,7 +3,7 @@
  * every request to the Worker endpoint with an Ed25519 private key; the
  * Runtime accepts only requests that verify against the public key.
  *
- * - The private key is a PKCS#8 PEM at `stack/restate-identity.pem` (mode
+ * - The private key is a PKCS#8 PEM at `docker/restate-identity.pem` (mode
  *   0600), mounted read-only into the restate service as
  *   `RESTATE_WORKER__INVOKER__REQUEST_IDENTITY_PRIVATE_KEY_PEM_FILE`.
  * - The public key goes to the Runtime as `NYLORUN_RESTATE_IDENTITY_KEY`, in