nylorun 0.4.0-beta → 0.6.0-beta

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

@@ -1,16 +1,19 @@
 /**
- * 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`.
+ * 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. Container, network and volume names are global on the Docker engine, so
+ * every one is `<project>-<role>` (`nylorun-shop-studio`, network `nylorun-shop`, volume
+ * `nylorun-shop-postgres`), labelled `dev.nylorun.tenant: <name>`; they are written here, from
+ * the project and the Tenant's name. Everything else that varies (ports, the Postgres password,
+ * UID/GID, the Host root, the images, Studio's public origins) comes from `docker/.env`.
  *
- * The Tenant's state is the stack's Postgres database, executed through Restate, with its
+ * 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, named after the stack (`NYLORUN_TENANT_NAME`), with the derived
+ * 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
@@ -33,4 +36,4 @@
  * 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(project: string): string;
+export declare function renderComposeFile(project: string, name: string): string;

package/dist/stack/compose-file.js

@@ -1,17 +1,20 @@
 import { PINNED_IMAGES } from "./images.js";
 /**
- * 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`.
+ * 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. Container, network and volume names are global on the Docker engine, so
+ * every one is `<project>-<role>` (`nylorun-shop-studio`, network `nylorun-shop`, volume
+ * `nylorun-shop-postgres`), labelled `dev.nylorun.tenant: <name>`; they are written here, from
+ * the project and the Tenant's name. Everything else that varies (ports, the Postgres password,
+ * UID/GID, the Host root, the images, Studio's public origins) comes from `docker/.env`.
  *
- * The Tenant's state is the stack's Postgres database, executed through Restate, with its
+ * 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, named after the stack (`NYLORUN_TENANT_NAME`), with the derived
+ * 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
@@ -34,13 +37,18 @@ import { PINNED_IMAGES } from "./images.js";
  * 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(project) {
+export function renderComposeFile(project, name) {
     return `# Written by \`nylorun start\`; rewritten on every start. Settings live in .env.
 name: ${project}
 
+x-tenant: &tenant
+  dev.nylorun.tenant: "${name}"
+
 services:
   postgres: # Session Store
     image: ${PINNED_IMAGES.postgres}
+    container_name: ${project}-postgres
+    labels: *tenant
     # 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:
@@ -59,9 +67,14 @@ services:
 
   restate: # Durable Session Execution
     image: ${PINNED_IMAGES.restate}
+    container_name: ${project}-restate
+    labels: *tenant
     command: ["--node-name=restate-1"] # stable name, so data is found on restart
     environment:
       RESTATE_WORKER__INVOKER__REQUEST_IDENTITY_PRIVATE_KEY_PEM_FILE: /run/nylorun/restate-identity.pem
+      # RocksDB's memory (block cache and memtables) defaults to 2 GiB; a local Tenant needs a
+      # fraction of it, and several Tenants share a laptop.
+      RESTATE_ROCKSDB_TOTAL_MEMORY_SIZE: 256MiB
     volumes:
       - restate:/restate-data
       - \${NYLORUN_HOST_ROOT:?run nylorun start}/docker/restate-identity.pem:/run/nylorun/restate-identity.pem:ro
@@ -74,20 +87,24 @@ services:
       retries: 30
     restart: unless-stopped
 
-  s2: # Durable Streams; not published, only the Runtime reaches it
+  s2-lite: # Durable Streams; not published, only the Runtime reaches it
     image: ${PINNED_IMAGES.s2}
+    container_name: ${project}-s2-lite
+    labels: *tenant
     command: ["lite", "--local-root", "/home/nonroot/data"] # local disk; listens on port 80
     # The image runs as uid 65532. Docker fills a new volume with the image's
     # /home/nonroot, owned by that user; a volume at a path the image lacks
     # (e.g. /data) is root-owned and s2-lite cannot write it.
     volumes:
-      - s2:/home/nonroot
+      - s2-lite:/home/nonroot
     # The s2 image has no shell or HTTP client, so it has no health check;
     # 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}
+    container_name: ${project}-gateway
+    labels: *tenant
     command: ["--service", "gates,keys"]
     user: "\${NYLORUN_UID:?run nylorun start}:\${NYLORUN_GID:?run nylorun start}"
     depends_on:
@@ -116,17 +133,19 @@ services:
 
   runtime:
     image: \${NYLORUN_RUNTIME_IMAGE:?run nylorun start}
+    container_name: ${project}-runtime
+    labels: *tenant
     command: ["--service", "core,loop"]
     user: "\${NYLORUN_UID:?run nylorun start}:\${NYLORUN_GID:?run nylorun start}"
     depends_on:
       postgres: { condition: service_healthy }
       restate: { condition: service_healthy }
-      s2: { condition: service_started }
+      s2-lite: { 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_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
@@ -136,12 +155,12 @@ services:
       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
@@ -149,7 +168,7 @@ services:
       NYLORUN_RESTATE_ADMIN_URL: http://restate:9070
       NYLORUN_WORKER_URL: http://runtime:9080 # registered with Restate; not published
       NYLORUN_RESTATE_IDENTITY_KEY: \${NYLORUN_RESTATE_IDENTITY_KEY:?run nylorun start}
-      NYLORUN_S2_ENDPOINT: http://s2:80
+      NYLORUN_S2_ENDPOINT: http://s2-lite: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.
@@ -158,7 +177,7 @@ 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/):
+      # 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
@@ -181,6 +200,8 @@ services:
 
   studio: # dashboard + trusted proxy
     image: \${NYLORUN_STUDIO_IMAGE:?run nylorun start}
+    container_name: ${project}-studio
+    labels: *tenant
     user: "\${NYLORUN_UID}:\${NYLORUN_GID}" # reads the 0600 admin key file
     depends_on:
       runtime: { condition: service_healthy }
@@ -188,10 +209,17 @@ services:
       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.
+      # Studio's Host check accepts localhost/127.0.0.1 on the published port, and the
+      # proxy's origin (http://<name>.localhost:<port>), kept in .env.
       NYLORUN_STUDIO_PUBLIC_PORT: \${NYLORUN_STUDIO_PORT}
+      NYLORUN_STUDIO_PUBLIC_ORIGINS: \${NYLORUN_STUDIO_PUBLIC_ORIGINS:-}
+      # Browsers share cookies across ports of one host: a cookie per Tenant keeps the
+      # sessions of two Studios on localhost apart.
+      NYLORUN_STUDIO_SESSION_COOKIE: nylorun_studio_${name}
       # 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:
@@ -203,10 +231,15 @@ services:
       retries: 30
     restart: unless-stopped
 
+networks:
+  default:
+    name: ${project}
+    labels: *tenant
+
 volumes:
-  postgres: {}
-  restate: {}
-  s2: {}
-  workspaces: {}
+  postgres: { name: ${project}-postgres, labels: *tenant }
+  restate: { name: ${project}-restate, labels: *tenant }
+  s2-lite: { name: ${project}-s2-lite, labels: *tenant }
+  workspaces: { name: ${project}-workspaces, labels: *tenant }
 `;
 }

package/dist/stack/docker.d.ts

@@ -36,3 +36,13 @@ export interface ComposeService {
 }
 /** Parse `docker compose ps --format json` (a JSON array, or one object per line). */
 export declare function parseComposePs(stdout: string): ComposeService[];
+/** `123.4MiB` (from `docker stats` MemUsage) in bytes; undefined when unreadable. */
+export declare function parseByteSize(text: string): number | undefined;
+/** `812 MB`, `2.1 GB`. */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Memory in use per Tenant: the sum over its running containers, found by the label
+ * `dev.nylorun.tenant`, from one `docker stats --no-stream`. Undefined when Docker does not
+ * answer; a Tenant with no running container is absent.
+ */
+export declare function tenantMemory(docker: DockerRunner): Promise<Map<string, number> | undefined>;

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)
@@ -99,3 +99,66 @@ export function parseComposePs(stdout) {
         };
     });
 }
+const UNITS = {
+    b: 1,
+    kb: 1e3,
+    mb: 1e6,
+    gb: 1e9,
+    tb: 1e12,
+    kib: 2 ** 10,
+    mib: 2 ** 20,
+    gib: 2 ** 30,
+    tib: 2 ** 40,
+};
+/** `123.4MiB` (from `docker stats` MemUsage) in bytes; undefined when unreadable. */
+export function parseByteSize(text) {
+    const match = /^([\d.]+)\s*([a-z]+)$/i.exec(text.trim());
+    const unit = match ? UNITS[match[2].toLowerCase()] : undefined;
+    return match && unit ? Number(match[1]) * unit : undefined;
+}
+/** `812 MB`, `2.1 GB`. */
+export function formatBytes(bytes) {
+    return bytes >= 1e9 ? `${(bytes / 1e9).toFixed(1)} GB` : `${Math.round(bytes / 1e6)} MB`;
+}
+/**
+ * Memory in use per Tenant: the sum over its running containers, found by the label
+ * `dev.nylorun.tenant`, from one `docker stats --no-stream`. Undefined when Docker does not
+ * answer; a Tenant with no running container is absent.
+ */
+export async function tenantMemory(docker) {
+    const ps = await docker.run([
+        "ps",
+        "--filter",
+        "label=dev.nylorun.tenant",
+        "--format",
+        '{{.Names}}\t{{.Label "dev.nylorun.tenant"}}',
+    ]);
+    if (ps.code !== 0)
+        return undefined;
+    const owners = new Map(ps.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim().split("\t"))
+        .filter((cells) => cells.length === 2 && cells[1] !== ""));
+    const memory = new Map();
+    if (owners.size === 0)
+        return memory;
+    const stats = await docker.run([
+        "stats",
+        "--no-stream",
+        "--format",
+        "{{.Name}}\t{{.MemUsage}}",
+        ...owners.keys(),
+    ]);
+    if (stats.code !== 0)
+        return undefined;
+    for (const line of stats.stdout.split(/\r?\n/)) {
+        const [name, usage] = line.trim().split("\t");
+        const tenant = name ? owners.get(name) : undefined;
+        const bytes = usage ? parseByteSize(usage.split("/")[0]) : undefined;
+        if (tenant && bytes !== undefined)
+            memory.set(tenant, (memory.get(tenant) ?? 0) + bytes);
+    }
+    for (const [tenant, bytes] of memory)
+        memory.set(tenant, Math.round(bytes));
+    return memory;
+}

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

@@ -29,8 +29,18 @@ 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;
+    /**
+     * The Google Analytics measurement id Studio reports page views to, or empty
+     * when telemetry is off. Decided again on every start.
+     */
+    studioAnalyticsId: string;
+    /**
+     * Origins Studio also serves besides localhost and 127.0.0.1 on its port, separated by
+     * spaces: the proxy's `http://<name>.localhost:<port>`, or empty. Decided on every start.
+     */
+    studioPublicOrigins: 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.

package/dist/stack/env-file.js

@@ -23,7 +23,9 @@ const KEYS = {
     runtimeImage: "NYLORUN_RUNTIME_IMAGE",
     studioImage: "NYLORUN_STUDIO_IMAGE",
     studioFrameAncestors: "NYLORUN_STUDIO_FRAME_ANCESTORS",
-    stackName: "NYLORUN_STACK_NAME",
+    studioAnalyticsId: "NYLORUN_STUDIO_ANALYTICS_ID",
+    studioPublicOrigins: "NYLORUN_STUDIO_PUBLIC_ORIGINS",
+    tenantName: "NYLORUN_TENANT_NAME",
     derivedPrincipals: "NYLORUN_DERIVED_PRINCIPALS",
 };
 /** Compose .env values: single quotes keep a value literal (no interpolation). */
@@ -76,10 +78,18 @@ 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",
+        "# 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"),
+        "",
+        "# Studio's address through the proxy (http://<name>.localhost:<port>); empty",
+        "# without the proxy. Set on every start.",
+        line("studioPublicOrigins"),
+        "",
+        "# 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("stackName"),
+        line("tenantName"),
         line("derivedPrincipals"),
         "",
     ].join("\n");

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;
@@ -36,7 +36,7 @@ export declare function readAdminKey(paths: StackPaths): Promise<string | undefi
 /**
  * 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.
+ * Host root before F4.2 kept it. The gateway never creates it.
  */
 export declare function ensureVaultKey(paths: StackPaths): Promise<{
     created: boolean;

package/dist/stack/host-files.js

@@ -8,10 +8,10 @@ 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}$/;
@@ -87,7 +87,7 @@ export async function readAdminKey(paths) {
 /**
  * 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.
+ * 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 });

package/dist/stack/images.d.ts

@@ -1,13 +1,14 @@
 /**
- * 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.
+ * images, pinned here, as is Caddy for the machine's Studio proxy.
  */
 export declare const PINNED_IMAGES: {
     readonly postgres: "postgres:17.11";
     readonly restate: "docker.restate.dev/restatedev/restate:1.7.12";
     readonly s2: "ghcr.io/s2-streamstore/s2:0.43.0";
+    readonly proxy: "caddy:2.11.6";
 };
 export interface StackImages {
     runtime: string;
@@ -15,6 +16,7 @@ export interface StackImages {
     postgres: string;
     restate: string;
     s2: string;
+    proxy: string;
 }
 /** `NYLORUN_RUNTIME_IMAGE` names the Runtime image, so its version is unknown here. */
 export declare function runtimeImageOverridden(env: Readonly<Record<string, string | undefined>>): boolean;

package/dist/stack/images.js

@@ -1,14 +1,15 @@
 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.
+ * images, pinned here, as is Caddy for the machine's Studio proxy.
  */
 export const PINNED_IMAGES = {
     postgres: "postgres:17.11",
     restate: "docker.restate.dev/restatedev/restate:1.7.12",
     s2: "ghcr.io/s2-streamstore/s2:0.43.0",
+    proxy: "caddy:2.11.6",
 };
 function override(env, name) {
     const value = env[name]?.trim();

package/dist/stack/index.d.ts

@@ -1,13 +1,14 @@
 import { type StackDeps } from "./commands.js";
-export { ensureStack, isStackCommand, readStackStatus, stackUsage, studioLoginUrl, tenantStudioPath, STACK_SERVICES, } from "./commands.js";
+export { ensureStack, isStackCommand, readProxyReport, readStackStatus, stackUsage, studioLoginUrl, tenantStudioPath, STACK_SERVICES, } from "./commands.js";
 export type { StackDeps, StackEndpoints, StackStatus, StackTenant } from "./commands.js";
 export { checkDocker } from "./docker.js";
 export type { Check, DockerChecks } from "./docker.js";
+export type { ProxyStatus } from "./proxy.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|ls|delete|legacy`. */
+/** 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` when given, else on the stack's Tenant. */
+/** `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

@@ -4,7 +4,7 @@ import { runStackCommand, runStudioCommand } from "./commands.js";
 import { spawnDocker } from "./docker.js";
 import { pinnedVersion } from "./versions.js";
 import { loopbackPorts } from "./ports.js";
-export { ensureStack, isStackCommand, readStackStatus, stackUsage, studioLoginUrl, tenantStudioPath, STACK_SERVICES, } from "./commands.js";
+export { ensureStack, isStackCommand, readProxyReport, readStackStatus, stackUsage, studioLoginUrl, tenantStudioPath, STACK_SERVICES, } from "./commands.js";
 export { checkDocker } from "./docker.js";
 function browserCommand(env) {
     if (process.platform === "darwin")
@@ -17,7 +17,13 @@ function browserCommand(env) {
  * 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"];
+const STACK_ENV_OWNED = [
+    "NYLORUN_TENANT_NAME",
+    "NYLORUN_DERIVED_PRINCIPALS",
+    "NYLORUN_STUDIO_ANALYTICS_ID",
+    "NYLORUN_STUDIO_PUBLIC_ORIGINS",
+    "NYLORUN_PROXY_PORT",
+];
 /** Real dependencies: docker on PATH, global fetch, the terminal. */
 export function defaultStackDeps(env) {
     const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
@@ -71,11 +77,11 @@ export function defaultStackDeps(env) {
         },
     };
 }
-/** Entry for `nylorun start|stop|status|logs|reset|studio|ls|delete|legacy`. */
+/** 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` when given, else on the stack's Tenant. */
+/** `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/stacks/<name>` 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,7 +8,7 @@ export interface StackPaths {
     credentials: string;
     /** host-state.json: written only by a launcher-managed Runtime. */
     state: string;
-    /** stack.json: the stack's name and the project it was created for. */
+    /** 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;

package/dist/stack/paths.js

@@ -7,7 +7,7 @@ export function stackPaths(hostRoot) {
         config: join(root, "host.json"),
         credentials: join(root, "host-credentials.json"),
         state: join(root, "host-state.json"),
-        record: join(root, "stack.json"),
+        record: join(root, "tenant.json"),
         tenant: join(root, "tenant"),
         keys: join(root, "keys"),
         vaultKey: join(root, "keys", "vault-kek"),

package/dist/stack/ports.d.ts

@@ -1,11 +1,13 @@
 export declare const DEFAULT_PORTS: {
+    /** The Studio proxy, one per machine (`http://<tenant>.localhost:<port>`). */
+    readonly proxy: 4160;
     readonly runtime: 8787;
     /** The Runtime's operator listener (Admin API). */
     readonly admin: 8788;
     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 +16,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>;

package/dist/stack/ports.js

@@ -1,5 +1,7 @@
 import { createServer } from "node:net";
 export const DEFAULT_PORTS = {
+    /** The Studio proxy, one per machine (`http://<tenant>.localhost:<port>`). */
+    proxy: 4160,
     runtime: 8787,
     /** The Runtime's operator listener (Admin API). */
     admin: 8788,
@@ -30,7 +32,7 @@ export const loopbackPorts = {
 };
 /**
  * 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 async function choosePort(probe, preferred, persisted, taken) {

package/dist/stack/prepare.d.ts

@@ -10,7 +10,7 @@ export interface PreparedStack {
     /** True when this run chose the ports (first start). */
     firstRun: boolean;
 }
-/** Read the persisted stack settings without writing anything. */
+/** Read the persisted Compose settings without writing anything. */
 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:
@@ -20,7 +20,7 @@ export declare function readStackEnv(paths: Pick<StackPaths, "env">): Promise<im
  */
 export declare function prepareStack(input: {
     paths: StackPaths;
-    /** The stack's name (its Tenant's name) and its Compose project. */
+    /** The Tenant's name and its Compose project. */
     name: string;
     project: string;
     images: StackImages;
@@ -29,7 +29,7 @@ export declare function prepareStack(input: {
     /** 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. */
+    /** Ports other Tenants 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;
@@ -41,4 +41,8 @@ export declare function prepareStack(input: {
         add?: readonly string[];
         reset?: boolean;
     };
+    /** The measurement id Studio reports page views to; absent when telemetry is off. */
+    studioAnalyticsId?: string;
+    /** Studio's origin through the proxy; absent without the proxy. */
+    studioPublicOrigin?: string;
 }): Promise<PreparedStack>;