nylorun 0.2.0-beta → 0.3.0-beta

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # nylorun
 
+## 0.3.0-beta
+
+### Minor Changes
+
+- e28b8a9: **New projects serve their tools as an Action endpoint.** Everything Nylorun ships now uses Action endpoints instead of executors. `connectAgents` still works, but it is deprecated.
+
+  - **Starter (`create-agent`).** `src/main.ts` serves the agents with `createActionHandler` on `http://localhost:3001/nylorun/actions` (`PORT`, `NYLORUN_ACTIONS_URL`) and registers it. `npm run dev` and `npm start` work as before. The README explains which URL the Runtime must reach.
+  - **Local stack (`nylorun`).** The Runtime container sets `NYLORUN_ENDPOINT_LOOPBACK=docker-host` and maps `host.docker.internal` to the Docker host, so a `localhost` endpoint on the developer's machine is reachable, on Linux Docker Engine too.
+  - **Examples.** The AG-UI and browser-direct apps serve their Action endpoint at `/nylorun/actions` beside their other routes, and `register(origin)` replaces `connection.ready`.
+  - **Docs.** The README, `DEPLOYMENT.md` and the `@nylorun/agents` README describe Action endpoints.
+
+- 50d0fb5: **The Admin API on its own listener.** A Runtime can serve the Admin API on an operator listener, so the port that faces browsers and reverse proxies serves the Tenant API alone. The stack does this by default.
+
+  - **Runtime.** With an operator listener (`adminPort` in `host.json`, or `NYLORUN_ADMIN_LISTEN_PORT`, `NYLORUN_ADMIN_LISTEN_HOST` and `NYLORUN_ADMIN_ALLOWED_HOSTS` in a container), the public listener answers `/v1/admin/**` with the opaque `404` and the operator listener serves the Admin API, Host shutdown and the Tenant API, never to browsers. Each checks `Host` against its own port. `/ready` needs both listening; a taken port on either exits with code 98. Without one, a single listener serves everything as before.
+  - **Stack.** `nylorun start` publishes the operator port on loopback (`NYLORUN_ADMIN_PORT`, default 8788), writes it to `host.json` as `adminPort`, and points Studio at `runtime:4001`. `nylorun status` prints it.
+  - **Admin client.** Reads `adminPort` from `host.json` and sends Admin API requests there (`admin.adminUrl`); `admin.url` stays the Tenant API URL. A `host.json` without `adminPort` keeps working.
+
+- 9546ac7: **The stream relay, ready to wire in.** The Runtime gains the relay that will feed S2 from a Postgres record of session events over logical replication (Durable Streams v1); nothing uses it yet.
+
+  - **Relay core** (`streams/relay/`): per-session pumps appending with `matchSeq`, acknowledgements only after S2 has the rows, refills from the record on a gap, reconciliation after a new or lost slot, and rows of an old basin generation dropped.
+  - **Change source** (`adapters/replication/pgoutput.ts`): a persistent `pgoutput` slot, one active process per slot, always resumed from the confirmed position; a pending reconciliation is kept in `nylorun_streams.relay_slots` so a crash cannot skip it.
+  - **Shared schema** (`nylorun_streams`): `session_events`, `session_log_heads`, `relay_slots` and the `nylorun_stream_relay` publication, migrated by the Host.
+  - **Basin generations**: `basinOf(tenantId, generation)` names a Tenant's later basins (`<basin>-<g base36>`).
+  - **Local stack**: Postgres runs with `wal_level=logical` and `max_slot_wal_keep_size=4GB`. `nylorun start` recreates the Postgres container once; its data volume is kept. `DEPLOYMENT.md` lists the settings for a Postgres you run yourself.
+
+- 9d52189: **Embedding Studio in a desktop app.** Studio can be shown inside a desktop app such as Babai Desktop, in an iframe loaded from its URL and signed in by `postMessage` with a token limited to one Tenant.
+
+  - **`nylorun`.** The local stack lets Babai's origins frame Studio: `NYLORUN_STUDIO_FRAME_ANCESTORS` in `stack/.env` defaults to `nylorun://localhost http://nylorun.localhost` and is passed to the Studio container. `nylorun start --studio-embed-origin <origin>` (repeatable) adds an exact origin, such as a desktop app's dev server, and keeps it across starts until `--studio-embed-origin-reset`. Wildcards are refused. `nylorun status` lists the origins under `Embeds`, and `status --json` as `studio.embedOrigins`.
+  - **`@nylorun/admin`.** `mintStudioLoginToken({ studioUrl, adminKey, tenant?, subject? })` mints a single-use Studio login token from an app's backend. With `tenant`, the session it leads to reaches only that Tenant.
+  - **Studio.** `POST /_studio/sessions` exchanges such a token for a one-hour bearer session kept in the frame's memory; dashboard pages send `frame-ancestors` from the allowlist instead of `X-Frame-Options: DENY`; `?embed=1` hides Studio's branding, follows the app's theme and routes, and reports its own; `/tenants/:tenant/sessions/:session` opens a session by id. The cookie login of `nylorun studio` is unchanged.
+
+    The dashboard routes `/tenants/:tenant`, `/tenants/:tenant/agents/:agent`, `/tenants/:tenant/agents/:agent/sessions/:session`, `/tenants/:tenant/sessions/:session`, `/tenants/:tenant/vault` and `/tenants/:tenant/settings` are now a public contract for embedders: removing or changing one is a breaking change.
+
+### Patch Changes
+
+- 4282d5f: **Breaking: executors are removed; protocol 3.** The Runtime delivers every Action (tool, hook, `fn`, `verify`) to the Action endpoint an agent registers. It no longer offers Actions for executors to claim. See `MIGRATION.md`, "Action endpoints replace executors".
+
+  - **Core.** `PROTOCOL_VERSION` is 3 and a Host serves only protocol 3. `action-endpoints` is a protocol feature instead of an optional Host feature. Removed:
+
+    - the executor, claim and Action-list schemas;
+    - `action_result` from `SessionCommandSchema`;
+    - the `claimed` Action status, `claimId` and `leaseExpiresAt`.
+
+    New: `ActionResultReceiptSchema`, the receipt of `POST /v1/actions/:id/result`, which is `AcceptedResponse` without `requestId`.
+
+  - **Runtime.** Removed:
+
+    - `PUT`/`GET /v1/executors`, `DELETE /v1/executors/:agentId`, `GET /v1/executors/connect`;
+    - `GET /v1/actions`, `POST /v1/actions/:id/claim`, and the executor form of `POST /v1/actions/:id/heartbeat`;
+    - the `tenant/work` stream;
+    - claim expiry;
+    - executor credentials.
+
+    `POST /v1/actions/:id/sandbox/:tool` takes the delivery token only. Tenant summaries report `inFlightDeliveries` instead of `connectedExecutors`. Tenant status lists each agent's endpoint and has an `endpoints` check instead of `executors`.
+
+    Postgres migration 6 drops the `executors` table. Actions an executor had claimed are handled like lost deliveries: a tool becomes `uncertain`, and a hook, `fn` or `verify` is delivered again.
+
+  - **Agents.** Removed: `connectAgents`, the `@nylorun/agents/executor` subpath, derived executor keys and `NYLORUN_EXECUTOR_KEY`. Serve agents with `createActionHandler` and call `register({ url })`.
+  - **CLI.** Executor keys are gone from Project credentials. `nylo tenant endpoints` shows each endpoint and its health.
+
+- c0f4623: `nylorun up`/`start` refuses to downgrade the shared stack. When this release pins a Runtime older than `host.json` `runtimeVersion` or the running Runtime's `/health` version, it exits 5 before changing the stack files or containers, and names the remedy: update nylorun, or pass the new `--allow-downgrade` flag. `nylorun studio` applies the same check when it starts the stack. With `NYLORUN_RUNTIME_IMAGE` set, the check is skipped and `host.json` keeps its recorded `runtimeVersion`.
+- Pin core to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [c7614a4]
+- Updated dependencies [679c488]
+- Updated dependencies [c85cd9e]
+- Updated dependencies [4282d5f]
+- Updated dependencies [82d95ef]
+- Updated dependencies [f48f12f]
+- Updated dependencies [50d0fb5]
+- Updated dependencies [50d0fb5]
+- Updated dependencies [c121144]
+- Updated dependencies [6ab4c59]
+- Updated dependencies [6ab4c59]
+- Updated dependencies [2ab8ed1]
+- Updated dependencies [c121144]
+- Updated dependencies [9546ac7]
+- Updated dependencies [9546ac7]
+- Updated dependencies [9d52189]
+- Updated dependencies [50d0fb5]
+- Updated dependencies [18468d9]
+  - @nylorun/core@0.9.0-beta
+
+## 0.2.1-beta
+
+### Patch Changes
+
+- db956bc: Studio creates Tenants. While the Host has none, Studio asks for a name and creates the first one. A Tenant with no agents shows **Connect your code**: its model provider, the `npx @nylorun/cli tenant use <id>` command, and `npm run dev`. It switches to the agent list when the first agent registers.
+
+  Every Tenant Studio creates registers the derived principal `project` (`PROJECT_PRINCIPAL_ID` in `@nylorun/admin`). `nylo tenant use` now falls back to that key, derived from the local admin key, so a Project links a Studio-created Tenant with no stored key. When it replaces a one-time application key, it keeps that key as `.nylorun/credentials.<tenantId>.json`, and `nylo tenant use <that id>` switches back. `nylorun up` again offers Studio for creating the first Tenant.
+
+- Pin studio to the tested release.
+
 ## 0.2.0-beta
 
 ### Minor Changes

package/README.md

@@ -29,7 +29,8 @@ npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the stack
 ## Commands
 
 ```sh
-nylorun up|start [--no-studio] [--no-open]  # set up (first run) and start the stack; print the Runtime and Studio URLs; open Studio signed in
+nylorun up|start [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]
+                                   # set up (first run) and start the stack; print the Runtime and Studio URLs; open Studio signed in
 nylorun down|stop                  # stop the containers; keep volumes
 nylorun status [--json]            # services, endpoints, Runtime health
 nylorun logs [service] [-f] [--tail <n>]   # postgres, restate, s2, runtime, studio
@@ -57,6 +58,14 @@ CI). Ports publish on loopback only: the Runtime on `8787`, Studio on `4161`
 and the Restate UI on `9070`, or free ports chosen on the first start and kept
 in `.env`. While the Host has no Tenant, `up` says how to create one.
 
+`up` never downgrades the stack on its own. Every project and app on the
+machine shares it, and a Runtime older than a Tenant's schema quarantines that
+Tenant. `up` records the pinned Runtime version in `host.json`
+(`runtimeVersion`) and exits 5 when that version is older than the one recorded
+there or the one running. Update nylorun, or pass `--allow-downgrade` to start
+the older Runtime anyway. With `NYLORUN_RUNTIME_IMAGE` set, the image's version
+is unknown: `up` does not check it and keeps the recorded version.
+
 `up` prints Studio as `http://localhost:<port>`. Studio has no password: in a
 terminal (not in CI, and not with `--no-open`), `up` asks the Studio container
 for a single-use login token with the admin key (`POST /_studio/login-tokens`)
@@ -68,6 +77,29 @@ browser in the same way; `nylorun studio --no-open` prints the login URL (it
 works once, for two minutes) instead. Inside a linked project, `nylorun studio`
 reads `.nylorun/link.json` (never writes it) and lands on that project's Tenant.
 
+### Embedding Studio in a desktop app
+
+A desktop app such as Babai Desktop can show Studio inside its own window, in
+an iframe loaded from Studio's URL (`studio.url` in `nylorun status --json`).
+Only exact origins listed in `NYLORUN_STUDIO_FRAME_ANCESTORS` (in
+`<Host root>/stack/.env`) may frame it. The default is Babai's
+`nylorun://localhost http://nylorun.localhost`; `nylorun status` lists them
+under `Embeds`. While building such an app, add its dev server once with
+`nylorun start --studio-embed-origin http://localhost:1420`; the list is kept
+across starts until `--studio-embed-origin-reset`. Wildcards are refused.
+
+The app's backend mints a single-use login token limited to one Tenant with
+`mintStudioLoginToken` from `@nylorun/admin` (it needs the admin key), and its
+page passes the token to Studio by `postMessage`. The message contract is
+`@nylorun/agents/studio-embed`.
+
+## Sandboxes
+
+A session gets a sandbox when it is opened with one, or when the Tenant's
+default names one (`PUT /v1/tenant/sandbox`). The stack runs them on the
+Runtime's **virtual** backend: an emulated shell in the Runtime process, with no
+extra containers. It is not a VM or container boundary.
+
 ## Host root
 
 The **Host root** is `NYLORUN_HOME` or `~/.nylorun`. It is bind-mounted into the
@@ -86,6 +118,7 @@ each with its own Tenant.
 | 2 | Usage error, or a removed or moved command |
 | 3 | `status`: the Runtime is not answering; `stop`/`logs`: no stack yet |
 | 4 | The Runtime port is held by another Host |
+| 5 | `up`/`start`/`studio`: this nylorun pins a Runtime older than the one the Host last ran or is running; update nylorun, or `up --allow-downgrade` |
 | 7 | The stack or Studio did not become ready |
 | 130 / 143 | SIGINT / SIGTERM |
 
@@ -95,6 +128,7 @@ each with its own Tenant.
 | --- | --- |
 | Docker missing or not running | Install or start Docker Desktop, OrbStack or Colima; `nylorun doctor` checks |
 | `426` from the Runtime | Upgrade nylorun (`npx nylorun@latest up`), or pin a matching older set |
+| `Refusing to downgrade` (exit 5) | Upgrade nylorun (`npx nylorun@latest up`); `--allow-downgrade` only if you accept quarantined Tenants |
 | Port conflict | Change `NYLORUN_PORT` / `NYLORUN_STUDIO_PORT` in `<Host root>/stack/.env` |
 | Logs | `nylorun logs runtime -f` |
 | Studio login expired | `nylorun studio` |

package/dist/stack/commands.d.ts

@@ -35,22 +35,27 @@ interface Flags {
     rest: string[];
     booleans: Set<string>;
     values: Map<string, string>;
+    /** Options that may repeat, in order. */
+    lists: Map<string, string[]>;
 }
 export declare function parseStackFlags(args: readonly string[], allowed: {
     booleans?: readonly string[];
     values?: readonly string[];
+    lists?: readonly string[];
     aliases?: Record<string, string>;
 }, usage: string): Flags;
 /** Printed by `start` when it does not open Studio itself. */
 export declare const STUDIO_SIGN_IN_HINT = "To sign a browser in to Studio, run \"npx nylorun studio\".";
 /** Printed by `start` while the Host has no Tenant: nylorun never creates one. */
-export declare const TENANT_HINT = "No Tenant yet. In your project, run `npx @nylorun/cli tenant create`.";
+export declare const TENANT_HINT = "No Tenant yet. Create one in Studio, or run `npx @nylorun/cli tenant create` in your project.";
 export interface StackStatus {
     project: string;
     home: string;
     state: "running" | "stopped" | "absent";
     runtime: {
         url?: string;
+        /** The Admin API (operator listener), when the stack publishes one. */
+        adminUrl?: string;
         healthy: boolean;
         version?: string;
         hostId?: string;
@@ -59,6 +64,8 @@ export interface StackStatus {
     studio: {
         url?: string;
         state: string;
+        /** Exact origins that may show Studio in a frame (Studio §8.9). */
+        embedOrigins?: string[];
     };
     restate: {
         url?: string;

package/dist/stack/commands.js

@@ -1,18 +1,21 @@
 import { existsSync } from "node:fs";
 import { readFile, rm, mkdir } from "node:fs/promises";
-import { PROTOCOL_HEADER, PROTOCOL_VERSION } from "@nylorun/core/compatibility";
+import { compareVersions, PROTOCOL_HEADER, PROTOCOL_VERSION, } from "@nylorun/core/compatibility";
 import { CliError } from "../errors.js";
 import { resolveHome } from "../home.js";
 import { dockerPreflight, parseComposePs, } from "./docker.js";
 import { readAdminKey, readHostConfig, STACK_CLIENT_HOST } from "./host-files.js";
-import { stackImages } from "./images.js";
+import { runtimeImageOverridden, stackImages } from "./images.js";
 import { stackPaths } from "./paths.js";
 import { prepareStack, readStackEnv } from "./prepare.js";
 import { mintStudioLogin, studioOrigin } from "./studio-login.js";
 export const STACK_SERVICES = ["postgres", "restate", "s2", "runtime", "studio"];
 const CORE_SERVICES = ["postgres", "restate", "s2", "runtime"];
 const DEFAULT_PROJECT = "nylorun";
-export const stackUsage = `  up|start [--no-studio] [--no-open]  set up the stack on first run, then start it; print the Runtime and Studio URLs and open Studio signed in (in a terminal)
+export const stackUsage = `  up|start [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]
+                                      set up the stack on first run, then start it; print the Runtime and Studio URLs and open Studio signed in (in a terminal).
+                                      refuses a Runtime older than the Host last ran unless --allow-downgrade.
+                                      --studio-embed-origin lets one more exact origin show Studio in a frame (a desktop app's development server); kept across starts until --studio-embed-origin-reset
   down|stop                           stop the stack's containers; keep volumes
   status [--json] [--env]             services, endpoints and Runtime health (--env: the linked Project's variables)
   logs [service] [-f] [--tail <n>]    stack logs (${STACK_SERVICES.join(", ")})
@@ -51,6 +54,7 @@ function requireStackFiles(ctx) {
 export function parseStackFlags(args, allowed, usage) {
     const booleans = new Set();
     const values = new Map();
+    const lists = new Map();
     const rest = [];
     for (let index = 0; index < args.length; index += 1) {
         const raw = args[index];
@@ -70,9 +74,16 @@ export function parseStackFlags(args, allowed, usage) {
             values.set(arg, value);
             continue;
         }
+        if (allowed.lists?.includes(arg)) {
+            const value = args[++index];
+            if (value === undefined || value.startsWith("-"))
+                throw usageError(`${arg} requires a value.`);
+            lists.set(arg, [...(lists.get(arg) ?? []), value]);
+            continue;
+        }
         throw usageError(`Unknown option ${raw}. Usage: ${usage}`);
     }
-    return { rest, booleans, values };
+    return { rest, booleans, values, lists };
 }
 async function sleep(ms) {
     await new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
@@ -135,9 +146,52 @@ function isUp(services, name) {
     const service = services.find((s) => s.service === name);
     return service?.state === "running" && (service.health === "" || service.health === "healthy");
 }
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/** `version` is a SemVer older than `than` (prereleases sort before releases). */
+function isOlder(version, than) {
+    return (typeof than === "string" &&
+        SEMVER.test(version) &&
+        SEMVER.test(than) &&
+        compareVersions(version, than) < 0);
+}
+/** The version of this Host's Runtime when it answers on the stack's port. */
+async function runningRuntimeVersion(ctx, hostId) {
+    const persisted = await readStackEnv(ctx.paths);
+    if (!persisted?.runtimePort || typeof hostId !== "string")
+        return undefined;
+    const health = await fetchHealth(ctx.deps, `http://${STACK_CLIENT_HOST}:${persisted.runtimePort}`);
+    return health?.status === "ok" && health.hostId === hostId ? health.version : undefined;
+}
+/**
+ * Refuse to start a Runtime older than the one the Host last ran (host.json
+ * `runtimeVersion`) or the one running now: Compose would replace it, every
+ * client on the machine shares the stack, and a Runtime older than a Tenant's
+ * schema quarantines that Tenant. Skipped when `NYLORUN_RUNTIME_IMAGE` names
+ * the image.
+ */
+async function refuseDowngrade(ctx, allowDowngrade) {
+    const pinned = ctx.deps.runtimeVersion;
+    const host = await readHostConfig(ctx.paths);
+    const newer = [];
+    if (isOlder(pinned, host?.runtimeVersion))
+        newer.push(`the Host last ran Runtime ${host.runtimeVersion} (${ctx.paths.config})`);
+    const running = await runningRuntimeVersion(ctx, host?.hostId);
+    if (isOlder(pinned, running) && running !== host?.runtimeVersion)
+        newer.push(`Runtime ${running} is running`);
+    if (newer.length === 0)
+        return;
+    if (allowDowngrade) {
+        ctx.deps.err(`Warning: downgrading to Runtime ${pinned}: ${newer.join(" and ")}. Tenants a newer Runtime migrated are quarantined.`);
+        return;
+    }
+    throw new CliError(`Refusing to downgrade: this nylorun pins Runtime ${pinned}, but ${newer.join(" and ")}. Every project and app on this machine shares the stack, and a Runtime older than a Tenant's schema quarantines that Tenant. Update nylorun (npx nylorun@latest up), or run "nylorun start --allow-downgrade" to start Runtime ${pinned} anyway.`, 5);
+}
 async function bringUp(ctx, options) {
     const { deps } = ctx;
     await refuseLauncherRuntime(ctx);
+    const overridden = runtimeImageOverridden(deps.env);
+    if (!overridden)
+        await refuseDowngrade(ctx, options.allowDowngrade ?? false);
     const prepared = await prepareStack({
         paths: ctx.paths,
         images: stackImages(deps.env, {
@@ -146,8 +200,10 @@ async function bringUp(ctx, options) {
         }),
         uid: deps.uid,
         gid: deps.gid,
-        runtimeVersion: deps.runtimeVersion,
+        // An overriding image's version is unknown: keep the recorded one.
+        runtimeVersion: overridden ? undefined : deps.runtimeVersion,
         ports: deps.ports,
+        ...(options.studioEmbedOrigins ? { studioEmbedOrigins: options.studioEmbedOrigins } : {}),
     });
     if (prepared.firstRun)
         deps.err(`Wrote ${ctx.paths.compose} and ${ctx.paths.env} (Runtime port ${prepared.env.runtimePort}, Studio port ${prepared.env.studioPort}).`);
@@ -203,14 +259,25 @@ async function openLogin(ctx, login) {
         ctx.deps.out(`Sign in   ${login}`);
 }
 /** Printed by `start` while the Host has no Tenant: nylorun never creates one. */
-export const TENANT_HINT = "No Tenant yet. In your project, run `npx @nylorun/cli tenant create`.";
+export const TENANT_HINT = "No Tenant yet. Create one in Studio, or run `npx @nylorun/cli tenant create` in your project.";
+const START_USAGE = "nylorun start [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]";
 async function start(ctx, args) {
-    const usage = "nylorun start [--no-studio] [--no-open]";
-    const flags = parseStackFlags(args, { booleans: ["--no-studio", "--no-open"] }, usage);
+    const flags = parseStackFlags(args, {
+        booleans: ["--no-studio", "--no-open", "--allow-downgrade", "--studio-embed-origin-reset"],
+        lists: ["--studio-embed-origin"],
+    }, START_USAGE);
     if (flags.rest.length)
-        throw usageError(`Usage: ${usage}`);
+        throw usageError(`Usage: ${START_USAGE}`);
     await dockerPreflight(ctx.deps.docker);
-    const started = await bringUp(ctx, { studio: !flags.booleans.has("--no-studio") });
+    const embedOrigins = flags.lists.get("--studio-embed-origin") ?? [];
+    const resetEmbed = flags.booleans.has("--studio-embed-origin-reset");
+    const started = await bringUp(ctx, {
+        studio: !flags.booleans.has("--no-studio"),
+        allowDowngrade: flags.booleans.has("--allow-downgrade"),
+        ...(embedOrigins.length || resetEmbed
+            ? { studioEmbedOrigins: { add: embedOrigins, reset: resetEmbed } }
+            : {}),
+    });
     ctx.deps.out(`Runtime   ${started.runtimeUrl}`);
     if (started.studioStarted) {
         ctx.deps.out(`Studio    ${studioOrigin(started.studioPort)}`);
@@ -280,8 +347,12 @@ async function stackStatus(ctx) {
     const health = runtimeUrl ? await fetchHealth(ctx.deps, runtimeUrl) : undefined;
     const host = await readHostConfig(ctx.paths);
     const healthy = health?.status === "ok" && (host === undefined || health.hostId === host.hostId);
-    const tenants = healthy && runtimeUrl
-        ? await adminTenantCount(ctx.deps, runtimeUrl, await readAdminKey(ctx.paths))
+    // The Admin API answers on the operator port; an older stack has only the Runtime port.
+    const adminUrl = persisted.adminPort
+        ? `http://${STACK_CLIENT_HOST}:${persisted.adminPort}`
+        : runtimeUrl;
+    const tenants = healthy && adminUrl
+        ? await adminTenantCount(ctx.deps, adminUrl, await readAdminKey(ctx.paths))
         : undefined;
     const studio = services.find((s) => s.service === "studio");
     return {
@@ -289,6 +360,7 @@ async function stackStatus(ctx) {
         state: services.some((s) => s.state === "running") ? "running" : "stopped",
         runtime: {
             ...(runtimeUrl ? { url: runtimeUrl } : {}),
+            ...(persisted.adminPort && adminUrl ? { adminUrl } : {}),
             healthy,
             ...(health?.version ? { version: health.version } : {}),
             ...(health?.hostId ? { hostId: health.hostId } : {}),
@@ -297,6 +369,9 @@ async function stackStatus(ctx) {
         studio: {
             ...(persisted.studioPort ? { url: studioOrigin(persisted.studioPort) } : {}),
             state: studio ? [studio.state, studio.health].filter(Boolean).join(", ") : "absent",
+            ...(persisted.studioFrameAncestors
+                ? { embedOrigins: persisted.studioFrameAncestors }
+                : {}),
         },
         restate: persisted.restatePort
             ? { url: `http://${STACK_CLIENT_HOST}:${persisted.restatePort}` }
@@ -326,7 +401,11 @@ async function status(ctx, args) {
             ? `healthy, ${result.runtime.version ?? "?"}, ${result.runtime.hostId ?? "?"}${result.runtime.tenants !== undefined ? `, ${result.runtime.tenants} Tenant(s)` : ""}`
             : "not answering";
         out(`Runtime     ${result.runtime.url ?? "?"}  ${runtimeDetail}`);
+        if (result.runtime.adminUrl)
+            out(`Admin API   ${result.runtime.adminUrl}  (operators only, never proxied)`);
         out(`Studio      ${result.studio.url ?? "?"}  ${result.studio.state} (log in with "nylorun studio")`);
+        if (result.studio.embedOrigins?.length)
+            out(`Embeds      ${result.studio.embedOrigins.join(" ")}  (may show Studio in a frame)`);
         if (result.restate.url)
             out(`Restate UI  ${result.restate.url}`);
         out(`Services    ${STACK_SERVICES.map((name) => {

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

@@ -5,7 +5,10 @@
  * Host root, the Runtime and Studio images) comes from `stack/.env`.
  *
  * Tenants are Postgres schemas, executed through Restate, with their history in
- * s2-lite; the Runtime's /ready checks all three.
+ * 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.
  *
  * Restate signs requests to the Worker endpoint with the private key in
  * `stack/restate-identity.pem`, mounted read-only; the Runtime gets the public

package/dist/stack/compose-file.js

@@ -6,7 +6,10 @@ import { PINNED_IMAGES } from "./images.js";
  * Host root, the Runtime and Studio images) comes from `stack/.env`.
  *
  * Tenants are Postgres schemas, executed through Restate, with their history in
- * s2-lite; the Runtime's /ready checks all three.
+ * 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.
  *
  * Restate signs requests to the Worker endpoint with the private key in
  * `stack/restate-identity.pem`, mounted read-only; the Runtime gets the public
@@ -19,6 +22,8 @@ name: nylorun
 services:
   postgres: # Session Store
     image: ${PINNED_IMAGES.postgres}
+    # Logical replication feeds the stream relay; a stuck slot is capped at 4 GB of WAL.
+    command: ["postgres", "-c", "wal_level=logical", "-c", "max_slot_wal_keep_size=4GB"]
     environment:
       POSTGRES_USER: nylorun
       POSTGRES_PASSWORD: \${NYLORUN_POSTGRES_PASSWORD:?run nylorun start}
@@ -77,6 +82,10 @@ services:
       # published port as clients on this machine address it.
       NYLORUN_ALLOWED_HOSTS: runtime:4000,localhost:\${NYLORUN_PORT},127.0.0.1:\${NYLORUN_PORT}
       NYLORUN_PUBLIC_URL: http://localhost:\${NYLORUN_PORT} # reported by /v1/admin/status
+      # The Admin API on its own listener, published on loopback only; Studio reaches it on
+      # the stack network. Port 4000 serves the Tenant API alone.
+      NYLORUN_ADMIN_LISTEN_PORT: "4001"
+      NYLORUN_ADMIN_ALLOWED_HOSTS: runtime:4001,localhost:\${NYLORUN_ADMIN_PORT},127.0.0.1:\${NYLORUN_ADMIN_PORT}
       NYLORUN_DATABASE_URL: postgres://nylorun:\${NYLORUN_POSTGRES_PASSWORD}@postgres:5432/nylorun
       NYLORUN_RESTATE_INGRESS_URL: http://restate:8080
       NYLORUN_RESTATE_ADMIN_URL: http://restate:9070
@@ -85,11 +94,16 @@ services:
       NYLORUN_S2_ENDPOINT: http://s2:80
       NYLORUN_S2_TOKEN: ignored # s2-lite has no access tokens yet
       NYLORUN_WORKSPACE_STORE_URL: file:///workspaces
+      # Action endpoints on this machine: \`localhost\` in a registered URL means the Docker host.
+      NYLORUN_ENDPOINT_LOOPBACK: docker-host
+    extra_hosts:
+      host.docker.internal: host-gateway # the Docker host, also on Linux Docker Engine
     volumes:
       - \${NYLORUN_HOST_ROOT:?run nylorun start}:/nylorun # Host root
       - workspaces:/workspaces
     ports:
-      - "127.0.0.1:\${NYLORUN_PORT:?run nylorun start}:4000" # Tenant API, Admin API, SSE
+      - "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))"]
       interval: 2s
@@ -103,11 +117,13 @@ services:
     depends_on:
       runtime: { condition: service_healthy }
     environment:
-      NYLORUN_RUNTIME_URL: http://runtime:4000
+      NYLORUN_RUNTIME_URL: http://runtime:4001 # the operator listener: Admin and Tenant API
       NYLORUN_ADMIN_KEY_FILE: /run/nylorun/host-credentials.json
       PORT: "3000"
       # Studio's Host check accepts localhost/127.0.0.1 on the published port.
       NYLORUN_STUDIO_PUBLIC_PORT: \${NYLORUN_STUDIO_PORT}
+      # Exact origins that may frame Studio (Babai Desktop); kept in .env.
+      NYLORUN_STUDIO_FRAME_ANCESTORS: \${NYLORUN_STUDIO_FRAME_ANCESTORS:-}
     volumes:
       - \${NYLORUN_HOST_ROOT}/host-credentials.json:/run/nylorun/host-credentials.json:ro
     ports:

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

@@ -1,10 +1,17 @@
+/**
+ * Origins that may embed Studio by default: Babai Desktop's `nylorun` scheme on
+ * macOS and Linux, and its WebView2 origin on Windows (Studio §8.9).
+ */
+export declare const DEFAULT_STUDIO_FRAME_ANCESTORS: readonly ["nylorun://localhost", "http://nylorun.localhost"];
 /**
  * Settings in `stack/.env` (mode 0600). Ports and the password persist; the
  * Restate identity public key is derived from `restate-identity.pem`.
  */
 export interface StackEnv {
-    /** Published Runtime port (loopback). */
+    /** Published Runtime port (loopback): the Tenant API. */
     runtimePort: number;
+    /** Published operator port (loopback): the Admin API. */
+    adminPort: number;
     /** Published Studio port (loopback). */
     studioPort: number;
     /** Published Restate UI and admin port (loopback). */
@@ -18,6 +25,8 @@ export interface StackEnv {
     hostRoot: string;
     runtimeImage: string;
     studioImage: string;
+    /** Exact origins that may frame Studio, separated by spaces (persists). */
+    studioFrameAncestors: string;
 }
 export declare function renderEnvFile(env: StackEnv): string;
 /** Parse KEY=value lines; comments and blank lines are skipped. */
@@ -25,8 +34,11 @@ export declare function parseEnvLines(text: string): Map<string, string>;
 /** The settings that persist across starts, from an existing .env. */
 export interface PersistedStackEnv {
     runtimePort?: number;
+    adminPort?: number;
     studioPort?: number;
     restatePort?: number;
     postgresPassword?: string;
+    /** Validated origins; absent when the line is missing (an older .env). */
+    studioFrameAncestors?: string[];
 }
 export declare function parsePersisted(text: string): PersistedStackEnv;

package/dist/stack/env-file.js

@@ -1,6 +1,16 @@
+import { parseFrameAncestors } from "@nylorun/core/contracts";
 import { CliError } from "../errors.js";
+/**
+ * Origins that may embed Studio by default: Babai Desktop's `nylorun` scheme on
+ * macOS and Linux, and its WebView2 origin on Windows (Studio §8.9).
+ */
+export const DEFAULT_STUDIO_FRAME_ANCESTORS = [
+    "nylorun://localhost",
+    "http://nylorun.localhost",
+];
 const KEYS = {
     runtimePort: "NYLORUN_PORT",
+    adminPort: "NYLORUN_ADMIN_PORT",
     studioPort: "NYLORUN_STUDIO_PORT",
     restatePort: "NYLORUN_RESTATE_PORT",
     postgresPassword: "NYLORUN_POSTGRES_PASSWORD",
@@ -10,6 +20,7 @@ const KEYS = {
     hostRoot: "NYLORUN_HOST_ROOT",
     runtimeImage: "NYLORUN_RUNTIME_IMAGE",
     studioImage: "NYLORUN_STUDIO_IMAGE",
+    studioFrameAncestors: "NYLORUN_STUDIO_FRAME_ANCESTORS",
 };
 /** Compose .env values: single quotes keep a value literal (no interpolation). */
 function quote(key, value) {
@@ -34,6 +45,7 @@ export function renderEnvFile(env) {
         "",
         "# Published on 127.0.0.1; clients use http://localhost:<port>.",
         line("runtimePort"),
+        line("adminPort"),
         line("studioPort"),
         line("restatePort"),
         "",
@@ -52,6 +64,10 @@ export function renderEnvFile(env) {
         line("runtimeImage"),
         line("studioImage"),
         "",
+        "# Exact origins that may show Studio in a frame (Babai Desktop). Kept across",
+        "# starts; change with nylorun start --studio-embed-origin <origin>.",
+        line("studioFrameAncestors"),
+        "",
     ].join("\n");
 }
 /** Parse KEY=value lines; comments and blank lines are skipped. */
@@ -80,6 +96,9 @@ export function parsePersisted(text) {
     const runtimePort = port(values.get(KEYS.runtimePort));
     if (runtimePort)
         out.runtimePort = runtimePort;
+    const adminPort = port(values.get(KEYS.adminPort));
+    if (adminPort)
+        out.adminPort = adminPort;
     const studioPort = port(values.get(KEYS.studioPort));
     if (studioPort)
         out.studioPort = studioPort;
@@ -89,5 +108,14 @@ export function parsePersisted(text) {
     const password = values.get(KEYS.postgresPassword);
     if (password && /^[A-Za-z0-9]{16,}$/.test(password))
         out.postgresPassword = password;
+    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);
+        }
+    }
     return out;
 }

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

@@ -13,6 +13,8 @@ export interface HostConfigFile {
     hostId: string;
     host: string;
     port: number;
+    /** The operator listener's published port (the Admin API); absent on older stacks. */
+    adminPort?: number;
     runtimeVersion?: string;
     [field: string]: unknown;
 }
@@ -21,12 +23,14 @@ export declare function newHostId(): string;
 export declare function ensureHostLayout(paths: StackPaths): Promise<void>;
 export declare function readHostConfig(paths: StackPaths): Promise<Record<string, unknown> | undefined>;
 /**
- * Write host.json with the published port. Keeps the hostId and unknown fields
- * of an existing file; refuses a newer format.
+ * Write host.json with the published port and the Runtime version that runs
+ * the Host. Keeps the hostId and unknown fields of an existing file, and its
+ * runtimeVersion when `runtimeVersion` is undefined; refuses a newer format.
  */
 export declare function writeStackHostConfig(paths: StackPaths, input: {
     port: number;
-    runtimeVersion: string;
+    adminPort?: number;
+    runtimeVersion: string | undefined;
 }): Promise<HostConfigFile>;
 export declare function readAdminKey(paths: StackPaths): Promise<string | undefined>;
 /** Create host-credentials.json (mode 0600) if missing; always leave it 0600. */

package/dist/stack/host-files.js

@@ -46,8 +46,9 @@ export async function readHostConfig(paths) {
     }
 }
 /**
- * Write host.json with the published port. Keeps the hostId and unknown fields
- * of an existing file; refuses a newer format.
+ * Write host.json with the published port and the Runtime version that runs
+ * the Host. Keeps the hostId and unknown fields of an existing file, and its
+ * runtimeVersion when `runtimeVersion` is undefined; refuses a newer format.
  */
 export async function writeStackHostConfig(paths, input) {
     const existing = (await readHostConfig(paths)) ?? {};
@@ -64,7 +65,8 @@ export async function writeStackHostConfig(paths, input) {
         hostId,
         host: STACK_CLIENT_HOST,
         port: input.port,
-        runtimeVersion: input.runtimeVersion,
+        ...(input.adminPort === undefined ? {} : { adminPort: input.adminPort }),
+        ...(input.runtimeVersion !== undefined ? { runtimeVersion: input.runtimeVersion } : {}),
     };
     await writeAtomic(paths.config, `${JSON.stringify(config, null, 2)}\n`);
     return config;

package/dist/stack/images.d.ts

@@ -16,6 +16,8 @@ export interface StackImages {
     restate: string;
     s2: string;
 }
+/** `NYLORUN_RUNTIME_IMAGE` names the Runtime image, so its version is unknown here. */
+export declare function runtimeImageOverridden(env: Readonly<Record<string, string | undefined>>): boolean;
 export declare function stackImages(env: Readonly<Record<string, string | undefined>>, versions?: {
     runtime: string;
     studio: string;

package/dist/stack/images.js

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

package/dist/stack/ports.d.ts

@@ -1,5 +1,7 @@
 export declare const DEFAULT_PORTS: {
     readonly runtime: 8787;
+    /** The Runtime's operator listener (Admin API). */
+    readonly admin: 8788;
     readonly studio: 4161;
     readonly restate: 9070;
 };

package/dist/stack/ports.js

@@ -1,6 +1,8 @@
 import { createServer } from "node:net";
 export const DEFAULT_PORTS = {
     runtime: 8787,
+    /** The Runtime's operator listener (Admin API). */
+    admin: 8788,
     studio: 4161,
     restate: 9070,
 };

package/dist/stack/prepare.d.ts

@@ -23,6 +23,15 @@ export declare function prepareStack(input: {
     images: StackImages;
     uid: number;
     gid: number;
-    runtimeVersion: string;
+    /** Recorded in host.json; undefined keeps the recorded version. */
+    runtimeVersion: string | undefined;
     ports: PortProbe;
+    /**
+     * Changes to the origins that may embed Studio: `reset` goes back to the
+     * defaults, `add` appends (for example a desktop app's dev server).
+     */
+    studioEmbedOrigins?: {
+        add?: readonly string[];
+        reset?: boolean;
+    };
 }): Promise<PreparedStack>;

package/dist/stack/prepare.js

@@ -1,7 +1,9 @@
 import { randomBytes } from "node:crypto";
 import { chmod, readFile, rename, writeFile } from "node:fs/promises";
 import { renderComposeFile } from "./compose-file.js";
-import { parsePersisted, renderEnvFile } from "./env-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 { choosePort, DEFAULT_PORTS } from "./ports.js";
 import { ensureIdentityKey } from "./restate-identity.js";
@@ -38,12 +40,26 @@ export async function prepareStack(input) {
     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 identity = await ensureIdentityKey(paths.restateIdentity, writeFileMode);
+    let added;
+    try {
+        added = parseFrameAncestors((input.studioEmbedOrigins?.add ?? []).join(" "));
+    }
+    catch (error) {
+        throw new CliError(`--studio-embed-origin: ${error instanceof Error ? error.message : String(error)}`, 2);
+    }
+    const base = input.studioEmbedOrigins?.reset || persisted.studioFrameAncestors === undefined
+        ? [...DEFAULT_STUDIO_FRAME_ANCESTORS]
+        : persisted.studioFrameAncestors;
+    const studioFrameAncestors = [...new Set([...base, ...added])].join(" ");
     const env = {
         runtimePort,
+        adminPort,
         studioPort,
         restatePort,
         postgresPassword: persisted.postgresPassword ?? randomBytes(24).toString("hex"),
@@ -53,10 +69,12 @@ export async function prepareStack(input) {
         hostRoot: paths.root,
         runtimeImage: input.images.runtime,
         studioImage: input.images.studio,
+        studioFrameAncestors,
     };
     const { adminKey } = await ensureHostCredentials(paths);
     const host = await writeStackHostConfig(paths, {
         port: runtimePort,
+        adminPort,
         runtimeVersion: input.runtimeVersion,
     });
     await writeFileMode(paths.env, renderEnvFile(env), 0o600);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylorun",
-  "version": "0.2.0-beta",
+  "version": "0.3.0-beta",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Set up and run the local Nylorun stack (Runtime and Studio) with Docker Compose",
@@ -30,7 +30,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nylorun/core": "0.8.0-beta"
+    "@nylorun/core": "0.9.0-beta"
   },
   "devDependencies": {
     "typescript": "npm:@typescript/typescript6@^6.0.2",
@@ -41,7 +41,7 @@
     "nylorun": "dist/cli.js"
   },
   "nylorun": {
-    "runtime": "0.13.0-beta",
-    "studio": "0.12.0-beta"
+    "runtime": "0.14.0-beta",
+    "studio": "0.14.0-beta"
   }
 }