nylorun 0.2.1-beta → 0.4.0-beta

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # nylorun
 
+## 0.4.0-beta
+
+### Major Changes
+
+- 5ca1923: **Clients for one Tenant per installation: a stack per project, nothing selects a Tenant.** Upgrade these with the Runtime; they speak protocol 5. Existing stacks are left as they are: see MIGRATION.md.
+
+  - **Breaking (`nylorun`): one stack per project.** `nylorun start` in a project creates the project's stack (named after the project directory, or `--name`; Host root `~/.nylorun/stacks/<name>/`, Compose project `nylorun-<name>`, its own free ports and volumes), waits for its Runtime to create the stack's Tenant, writes the Project link (`.nylorun/link.json` format 2: `stack`, `hostUrl`, `hostId`, `tenantId`) and `.nylorun/credentials.json` (the key of the derived principal `project`, derived from the stack's admin key), and seeds the model provider from the project's `.env`. `nylorun ls` lists the machine's stacks and `nylorun delete <name>` removes one with its volumes and Host root. `nylorun status` shows the stack's Tenant; `nylorun studio` opens it. The old single stack under `~/.nylorun` is never touched: `start` notes it, and `nylorun legacy stop|delete` handles it. Every stack command takes `--name <stack>` (or `NYLORUN_STACK`, or the Project link's stack); `start --no-link` starts a stack without linking the directory; `nylorun reset` resets the selected stack only. The runtime container's healthcheck is now `/health`, so a Tenant that cannot open is reported by `start` from the Admin status at once instead of after a 300 s wait. `NYLORUN_HOME` still overrides the Host root. Stacks start and stop only when you say so.
+  - **Breaking (`@nylorun/cli`): no Tenant commands.** `nylo tenant create|use|list|current|delete` are removed; `nylo status`, `nylo reset` and `nylo endpoints` replace `nylo tenant status|reset|endpoints` on the linked installation. `nylo env` prints `NYLORUN_RUNTIME_URL` and `NYLORUN_SERVER_KEY` only. `nylo` no longer writes Project links.
+  - **Breaking (`@nylorun/agents`): no Tenant to name.** The `tenant` option (`createClient`, `Transport`, `resolveConnection`, `createActionHandler({ runtime })`, `JwksCache`) and `NYLORUN_TENANT` are gone, and no request sends `Nylorun-Tenant`; a connection is a URL and a key. A Project link of format 0 or 1 is refused with `connection_missing`, naming `npx nylorun start`. `verifyDeliveryToken`'s `tenantId` is optional: without it any Tenant issuer is accepted, since the installation's keys bind it. `TENANT_HEADER` is no longer re-exported.
+  - **Breaking (`@nylorun/admin`): status only.** `createTenant`, `listTenants`, `getTenant` and `deleteTenant` are removed; `status().tenant` names the Host's Tenant, and `deriveTenantKey` / `deriveStudioToken` derive its keys. Local Host resolution reads the stack's Host root (`stack` option, `NYLORUN_STACK`, or the Project link's `stack`); `NYLORUN_HOME` and `home` still override it. `stackHostRoot(name)` is exported.
+  - **Breaking (`@nylorun/studio`): Studio serves its installation's Tenant.** The Tenant picker, list and create are gone, with `/_studio/tenants`; `/` opens `/tenants/<id>`. The `/tenants/:tenant` routes and the login token's `tenant` claim stay for embedders and must name that Tenant. The proxy sends no `Nylorun-Tenant`.
+  - **`@nylorun/create-agent`:** the next steps are `npx nylorun start`, then `npm run dev`.
+  - `@nylorun/core`: `ProjectLinkFileSchema` accepts format 2 with `stack`, and `tenantId` is optional; `ERROR_CODES` loses `tenant_conflict` and `active_work`.
+
+### Minor Changes
+
+- ee9e471: **Only the gateway can read the vault key (F4.2).** `nylorun start` writes the Tenant's vault key to `<Host root>/keys/vault-kek`. Only the `gateway` container mounts `keys/`, read-only, and runs `--service gates,keys`. The runtime container covers `keys/` and `docker/` with empty read-only mounts, so it reads neither the vault key nor Restate's private key and `.env`. `nylorun reset` deletes the key with the Tenant's data.
+- e3af093: **A stack's Docker Compose files live in `docker/`.** `compose.yaml`, `.env` and `restate-identity.pem` are written to `~/.nylorun/stacks/<name>/docker/` (or `$NYLORUN_HOME/docker/`), so the folder says what it holds: to change a port, edit `docker/.env`. The single stack of older releases keeps its `~/.nylorun/stack/`, which `nylorun legacy` reads as it is.
+- 7bd38d6: **The local stack runs a gateway container: model calls leave the Runtime.** `nylorun up` now runs the Runtime image twice, the combined packing: `runtime` (`--service core,loop`: the APIs and the agent loop) and `gateway` (`--service gates,keys`: the Model Gate, the Tool Gate and the keys service). Every model call, remote MCP call and Action delivery of the loop crosses the gateway, which alone reads the Tenant's credentials and the vault key. A new stack starts with the gateway.
+
+  - **Breaking for hand-written Compose files:** in a container, a Runtime that runs `loop` refuses to start without `NYLORUN_GATES_URL` and `NYLORUN_GATES_TOKEN`. Run the image a second time with `--service gates,keys` (see `DEPLOYMENT.md`). The image's default command is now `--service core,loop`.
+  - The gateway has no published port, mounts only the Host's Tenant directory (`tenant/`) and `keys/`, both read-only, and reaches model servers on this machine at `host.docker.internal`. `docker/.env` holds `NYLORUN_GATES_TOKEN`, generated once and kept across starts.
+  - `nylorun status` shows a Gateway line, `nylorun doctor` fails when the gateway is unhealthy and names `nylorun logs gateway`, and `nylorun logs gateway` is accepted.
+  - An image set with `NYLORUN_RUNTIME_IMAGE` must be this release or newer: older Runtimes don't know `--service`.
+
+- 31cfec0: **Action deliveries leave through the gateway (F4.1).** With the gates service, every delivery and endpoint ping is POSTed by the gateway (`POST /nylorun/v1/deliveries`) under the gateway's own `NYLORUN_ENDPOINT_*` policy. The delivery state machine is unchanged. A gateway that cannot be reached counts as a delivery that was not sent, so it is retried, and its failure code is `gateway.unreachable`.
+
+  - `nylorun`: the `gateway` container now sets `NYLORUN_ENDPOINT_LOOPBACK=docker-host`, so Action endpoints on this machine stay reachable.
+  - A process that runs only `core` also reads `NYLORUN_GATES_URL`, for endpoint pings.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [fed780d]
+- Updated dependencies [fed780d]
+- Updated dependencies [7f4c3f1]
+- Updated dependencies [5ca1923]
+- Updated dependencies [5ca1923]
+  - @nylorun/core@0.10.0-beta
+
+## 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

package/README.md

@@ -1,17 +1,22 @@
 # nylorun
 
-Sets up and runs the local Nylorun stack: the Runtime and Studio, as a Docker
-Compose stack. It needs nothing in your project; run it with `npx`:
+Sets up and runs local Nylorun stacks: the Runtime and Studio, as Docker
+Compose stacks, one per project. It needs nothing in your project; run it with
+`npx` in the project's directory:
 
 ```sh
-npx nylorun up      # set up the stack on the first run, then start it
-npx nylorun down    # stop it; volumes (and Tenants) are kept
+npx nylorun start   # create (first run) and start this project's stack, its Tenant and the Project link
+npx nylorun stop    # stop it; volumes (and the Tenant's data) are kept
 ```
 
-`nylorun` only manages the stack. It never creates Tenants: create one in
-Studio, or with the Runtime client, [`@nylorun/cli`](../cli/README.md) (command
-`nylo`), which also links a project to it. Depends on `@nylorun/core` only
-among Nylorun packages and never imports `@nylorun/runtime`. Vocabulary:
+A stack is one installation: one Runtime with its own Postgres, Restate and
+S2, serving exactly one Tenant. `nylorun start` in a project creates the
+project's stack, the Runtime creates the stack's Tenant on its first start,
+and `nylorun start` links the project to it. There are no Tenant commands:
+projects that must not share agents, credentials or history run separate
+stacks. Agents, sessions and model providers belong to the Runtime client,
+[`@nylorun/cli`](../cli/README.md) (command `nylo`). Depends on `@nylorun/core`
+only among Nylorun packages and never imports `@nylorun/runtime`. Vocabulary:
 [runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
 
 Prerequisites, installed by the developer (nylorun never downloads them): Node
@@ -29,53 +34,155 @@ 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 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
-nylorun studio [--no-open]         # sign a browser in to Studio (on the linked Project's Tenant); starts the stack if needed
-nylorun reset [--yes]              # delete the stack's volumes and every Tenant
+nylorun up|start [--name <stack>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]
+                                   # create (first run) and start the stack; link the project; print the URLs; open Studio signed in
+nylorun down|stop [--name <stack>] # stop the containers; keep volumes
+nylorun status [--name <stack>] [--json]   # the stack, its Host root and Tenant, services, endpoints, Runtime health
+nylorun logs [service] [--name <stack>] [-f] [--tail <n>]   # postgres, restate, s2, gateway, runtime, studio
+nylorun studio [--name <stack>] [--no-open]   # sign a browser in to Studio on the stack's Tenant; starts the stack if needed
+nylorun reset [--name <stack>] [--yes]        # delete the stack's volumes and Tenant directory; the next start creates a new Tenant
+nylorun ls [--json]                # the stacks on this machine
+nylorun delete <stack> --yes       # remove a stack: containers, volumes, Host root and vault key
+nylorun legacy stop|delete [--yes] # the single stack of older releases
 nylorun doctor [--json]            # prerequisites and stack health
 ```
 
 `up` and `down` are the Docker Compose spellings of `start` and `stop`: `down`
 stops the containers and keeps the volumes, so no Tenant data is lost.
-`nylorun stack <command>` still works as a hidden alias. Commands that act on a
-Tenant moved to the Runtime client and exit 2 naming the replacement:
-`nylorun dev`, `nylorun tenant …`, `nylorun configure`, `nylorun status --env`
-and `nylorun doctor sandbox`.
+`nylorun stack <command>` still works as a hidden alias. Removed commands exit
+2 naming the replacement: `nylorun tenant …` (`nylorun start` creates the
+Tenant; `nylorun status|reset`, or `nylo status|reset|endpoints`), `nylorun
+dev`, `nylorun configure`, `nylorun status --env` and `nylorun doctor sandbox`.
+
+## Stacks
+
+Every command acts on one stack, chosen in this order:
+
+1. `--name <stack>`;
+2. `NYLORUN_STACK`;
+3. the stack in the project's link (`.nylorun/link.json`, found from the
+   working directory upwards);
+4. for `start` in a project only: the project directory's name, lowercased,
+   with characters outside `[a-z0-9_-]` as `-`, and a suffix (`-2`, `-3`, …)
+   when a stack of that name was created for another project directory.
+
+Outside a project, `start` needs `--name`, and the other commands need
+`--name`, `NYLORUN_STACK` or a linked project. `nylorun ls` lists the stacks.
+
+Each stack has its own Host root `~/.nylorun/stacks/<name>/`, Compose project
+`nylorun-<name>` (`NYLORUN_STACK_PROJECT` overrides it), volumes, network and
+ports. `NYLORUN_HOME` replaces the whole Host root (the stack's name then comes
+from its `stack.json`, the project directory or the Host root's own name).
+
+A stack refuses only a Runtime older than its own database: `start` records
+the pinned Runtime version in `host.json` (`runtimeVersion`) and exits 5 when
+this nylorun pins an older one. Update nylorun, or pass `--allow-downgrade`
+when both versions use the same database schema (otherwise the Runtime reports
+the Tenant unavailable, `schema-too-new`). With `NYLORUN_RUNTIME_IMAGE` set,
+the image's version is unknown: `start` does not check it and keeps the
+recorded version.
+
+## The Project link
+
+`nylorun start` in a project waits until the stack's Tenant is open
+(`/v1/admin/status`), then writes, in a `.nylorun/` directory (mode 0700, with
+its own `.gitignore` of `*`):
+
+- `link.json`: `{ "format": 2, "stack", "hostUrl", "hostId", "tenantId" }`.
+  The Tenant id is information only: nothing in a request selects a Tenant.
+- `credentials.json` (mode 0600): the key of the derived principal `project`,
+  derived from the stack's admin key, and its id.
+
+Later starts reuse the stack and rewrite the link only when the stack, its URL,
+Host or Tenant changed (after `nylorun reset`, for example). When it writes a
+new link, `start` seeds the Tenant from the project's `.env`: the sandbox
+backend (`NYLORUN_SANDBOX=auto|virtual`) and the model credential
+(`MODEL_PROVIDER`, `MODEL`, `MODEL_PROVIDER_API_KEY`, `MODEL_PROVIDER_BASE_URL`,
+or `.nylorun/auth.json`), unless the Tenant has a model or
+`NYLORUN_DEV_MODEL=fixture`. `.env` never configures the stack itself.
+
+A fresh clone or a second worktree has no link: `nylorun start` there creates a
+new stack, or `nylorun start --name <stack>` attaches it to an existing one so
+both share the stack's Tenant. `--no-link` starts a stack without linking the
+working directory (scripts). A link of format 0 or 1 named a Tenant on the
+shared stack of an older Runtime: `start` says so, creates the project's own
+stack and replaces the link.
+
+The Runtime registers the derived principals of `NYLORUN_DERIVED_PRINCIPALS`
+(comma-separated, from the environment of `nylorun start`, kept in the stack's
+`.env`) when it creates the Tenant; `project` is always among them.
 
 ## The stack
 
-`nylorun up` writes `compose.yaml` and `.env` (mode 0600) under
-`<Host root>/stack/` on the first run and reuses them after that. It runs the
-Compose project `nylorun` (override with `NYLORUN_STACK_PROJECT`): `postgres`,
-`restate`, `s2`, `runtime` and `studio`. The Runtime and Studio images are
-pinned by this release (`package.json` `nylorun.runtime` and `nylorun.studio`);
+`nylorun start` writes `compose.yaml` and `.env` (mode 0600) under
+`~/.nylorun/stacks/<name>/docker/` on the first run and reuses them after that: `postgres`,
+`restate`, `s2`, `gateway`, `runtime` and `studio`. Postgres initialises the
+stack's database with C collation. The Runtime and Studio images are pinned by
+this release (`package.json` `nylorun.runtime` and `nylorun.studio`);
 `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them (local builds,
-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.
+CI). Ports publish on loopback only: the Runtime on `8787`, its operator
+listener (Admin API) on `8788`, Studio on `4161` and the Restate UI on `9070`,
+or free ports chosen on the stack's first start, avoiding the ports other
+stacks keep, and kept in its `.env`.
 
-`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
+`start` prints Studio as `http://localhost:<port>`. Studio has no password: in a
+terminal (not in CI, and not with `--no-open`), `start` asks the Studio container
 for a single-use login token with the admin key (`POST /_studio/login-tokens`)
-and opens `http://localhost:<port>/login?token=…` in the browser. That sets a
-session cookie for 30 days, which survives Studio restarts, so the printed URL
-keeps working in that browser. The token itself is never printed unless no
-browser starts. Otherwise `up` says to run `nylorun studio`, which signs a
-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.
+and opens `http://localhost:<port>/login?token=…` on the stack's Tenant in the
+browser. That sets a session cookie for 30 days, which survives Studio
+restarts, so the printed URL keeps working in that browser. The token itself is
+never printed unless no browser starts. Otherwise `start` says to run `nylorun
+studio`, which signs a browser in the same way; `nylorun studio --no-open`
+prints the login URL (it works once, for two minutes) instead.
+
+### 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
+`~/.nylorun/stacks/<name>/docker/.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 for the stack's 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
-Runtime and Studio containers, and holds `host.json` (the client-facing host
-and port), `host-credentials.json` (the admin key, mode 0600), the stack files
-and each Tenant's directory. Tenant data lives in the stack's Postgres, Restate
-and S2 volumes. The stack is one per machine: every project on it shares it,
-each with its own Tenant.
+The **Host root** is `~/.nylorun/stacks/<name>/`, or `NYLORUN_HOME`. It is
+bind-mounted into the Runtime and Studio containers, and holds `stack.json`
+(the stack's name and the project it was created for), `host.json` (the
+client-facing host and port), `host-credentials.json` (the admin key, mode
+0600), the Docker Compose files in `docker/`, the Tenant directory `tenant/` (homes, logs) and
+`keys/vault-kek`, the Tenant's vault key, which only the gateway container
+mounts. The Tenant's data lives in the stack's Postgres, Restate and S2
+volumes.
+
+`nylorun reset` deletes the selected stack's volumes, `tenant/` and `keys/`, and keeps
+its files and ports; the next start creates a new Tenant and relinks the
+project. `nylorun delete <stack> --yes` removes the stack's containers,
+volumes and Host root: the vault key (KEK) and all the Tenant's data go with it.
+
+## Upgrading from a shared stack
+
+Older releases ran one stack per machine (Compose project `nylorun`, Host root
+`~/.nylorun`) with a Tenant per project. This release starts fresh and leaves
+that stack as it is: `nylorun start` mentions it once, and `nylorun ls` shows
+it. `nylorun legacy stop` stops it; `nylorun legacy delete --yes` removes its
+containers, volumes and files under `~/.nylorun` (never `~/.nylorun/stacks`).
+Model credentials come from each project's `.env` (or Studio), and agents
+register again (`npm run dev`). See [MIGRATION.md](../MIGRATION.md).
 
 ## Exit codes
 
@@ -83,10 +190,11 @@ each with its own Tenant.
 | --- | --- |
 | 0 | Success |
 | 1 | Generic failure, including a missing Docker or Compose v2 |
-| 2 | Usage error, or a removed or moved command |
-| 3 | `status`: the Runtime is not answering; `stop`/`logs`: no stack yet |
+| 2 | Usage error (including no stack selected, or `delete` without `--yes`), or a removed or moved command |
+| 3 | `status`: the Runtime is not answering; `stop`/`logs`: no stack yet; `delete`: no such stack |
 | 4 | The Runtime port is held by another Host |
-| 7 | The stack or Studio did not become ready |
+| 5 | `up`/`start`/`studio`: this nylorun pins a Runtime older than the one that last ran the stack; update nylorun, or `start --allow-downgrade` |
+| 7 | The stack, its Tenant or Studio did not become ready (an unavailable Tenant's cause is printed) |
 | 130 / 143 | SIGINT / SIGTERM |
 
 ## Troubleshooting
@@ -94,8 +202,10 @@ each with its own Tenant.
 | Symptom | What to do |
 | --- | --- |
 | 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 |
-| Port conflict | Change `NYLORUN_PORT` / `NYLORUN_STUDIO_PORT` in `<Host root>/stack/.env` |
+| `426` from the Runtime | Upgrade nylorun (`npx nylorun@latest start`), or pin a matching older set |
+| `Refusing to start Runtime …` (exit 5) | Upgrade nylorun (`npx nylorun@latest start`); `--allow-downgrade` only when both Runtimes share the database schema |
+| `The Tenant of stack … is unavailable` (exit 7) | Follow the repair it names; `nylorun logs runtime` |
+| Port conflict | Change `NYLORUN_PORT` / `NYLORUN_STUDIO_PORT` in `~/.nylorun/stacks/<name>/docker/.env` |
 | Logs | `nylorun logs runtime -f` |
 | Studio login expired | `nylorun studio` |
 

package/dist/cli.js

@@ -2,23 +2,26 @@
 import "./baseline.js";
 import { baselineEnv } from "./baseline.js";
 import { CliError } from "./errors.js";
-import { linkedTenantId } from "./project/link.js";
-import { isStackCommand, stackCommand, stackUsage, studioCommand, tenantStudioPath, } from "./stack/index.js";
-const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|doctor>
+import { isStackCommand, stackCommand, stackUsage, studioCommand, } from "./stack/index.js";
+const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|ls|delete|legacy|doctor>
 
-Local stack (Docker Compose):
+Local stacks (Docker Compose), one per project:
 ${stackUsage}
   doctor [--json]                     check Node, Docker and Compose v2, and the stack's health
 
-nylorun sets up and runs the local stack. Tenants, Project links and model
+A command acts on the stack --name or NYLORUN_STACK names, else the linked project's;
+NYLORUN_HOME sets its Host root (default ~/.nylorun/stacks/<name>).
+
+nylorun sets up and runs local stacks. "nylorun start" in a project creates the
+project's stack, its one Tenant and the Project link. Agents, sessions and model
 providers belong to the Runtime client: npx @nylorun/cli --help`;
 const CLIENT = "npx @nylorun/cli";
-/** Commands that moved to the Runtime client (`@nylorun/cli`, command `nylo`). */
+/** Commands that were removed, or moved to the Runtime client (`@nylorun/cli`, command `nylo`). */
 const MOVED_TO_CLIENT = {
-    dev: `nylorun dev was removed: run \`${CLIENT} tenant create\` once in your project, then your project's \`npm run dev\`.`,
-    tenant: `Tenant commands moved to the Runtime client: ${CLIENT} tenant …`,
+    dev: "nylorun dev was removed: run `npx nylorun start` in your project (it creates the project's stack, its Tenant and the Project link), then your project's `npm run dev`.",
+    tenant: `Tenant commands were removed: a stack serves one Tenant, which \`npx nylorun start\` in a project creates with the stack and the Project link. Use nylorun status|reset, or ${CLIENT} status|reset|endpoints.`,
     configure: `nylorun configure moved to the Runtime client: ${CLIENT} configure`,
-    serve: "nylorun serve was removed. Use node dist/src/main.js with NYLORUN_RUNTIME_URL, NYLORUN_TENANT and NYLORUN_SERVER_KEY.",
+    serve: "nylorun serve was removed. Use node dist/src/main.js with NYLORUN_RUNTIME_URL and NYLORUN_SERVER_KEY.",
     runtime: "nylorun runtime was removed: the local Runtime runs in the Docker Compose stack. Use nylorun up|down|status|logs.",
 };
 const LOCAL_UI_REMOVED = "--local-ui was removed: Studio runs in the stack's studio container. Run nylorun studio.";
@@ -37,8 +40,7 @@ async function main() {
     if (command === "studio") {
         if (args.includes("--local-ui"))
             throw usageError(LOCAL_UI_REMOVED);
-        const tenantId = await linkedTenantId();
-        process.exitCode = await studioCommand(args, baselineEnv(), tenantId ? { next: tenantStudioPath(tenantId) } : {});
+        process.exitCode = await studioCommand(args, baselineEnv());
         return;
     }
     if (isStackCommand(command)) {

package/dist/doctor.d.ts

@@ -6,7 +6,9 @@ export interface StackDoctorReport {
     };
     docker: Check;
     compose?: Check;
-    stack?: Pick<StackStatus, "project" | "home" | "state" | "runtime" | "studio">;
+    stack?: Pick<StackStatus, "name" | "project" | "home" | "state" | "runtime" | "tenant" | "studio" | "gateway">;
+    /** Why no stack was checked: none is selected here (no link, NYLORUN_STACK or NYLORUN_HOME). */
+    noStack?: string;
 }
 /**
  * `nylorun doctor`: check the prerequisites of the local stack (Node 24+,

package/dist/doctor.js

@@ -1,3 +1,4 @@
+import { CliError } from "./errors.js";
 import { checkDocker, defaultStackDeps, readStackStatus, } from "./stack/index.js";
 /** Oldest Node the stack's tooling and the developer's application run on. */
 const MIN_NODE_MAJOR = 24;
@@ -17,16 +18,29 @@ export async function doctorStack(options) {
         ...checks,
     };
     if (checks.docker.ok && checks.compose?.ok) {
-        const status = await readStackStatus(deps);
-        report.stack = {
-            project: status.project,
-            home: status.home,
-            state: status.state,
-            runtime: status.runtime,
-            studio: status.studio,
-        };
+        try {
+            const status = await readStackStatus(deps);
+            report.stack = {
+                name: status.name,
+                project: status.project,
+                home: status.home,
+                state: status.state,
+                runtime: status.runtime,
+                ...(status.tenant ? { tenant: status.tenant } : {}),
+                studio: status.studio,
+                gateway: status.gateway,
+            };
+        }
+        catch (error) {
+            if (!(error instanceof CliError) || error.exitCode !== 2)
+                throw error;
+            report.noStack = error.message;
+        }
     }
-    const stackBroken = report.stack?.state === "running" && !report.stack.runtime.healthy;
+    const stackBroken = report.stack?.state === "running" &&
+        (!report.stack.runtime.healthy ||
+            !report.stack.gateway.healthy ||
+            report.stack.tenant?.cause !== undefined);
     const failed = !nodeOk || !checks.docker.ok || checks.compose?.ok === false || stackBroken;
     if (options.json) {
         log(JSON.stringify(report, null, 2));
@@ -48,16 +62,18 @@ export async function doctorStack(options) {
         ["compose", line(checks.compose)],
     ];
     const stack = report.stack;
+    if (report.noStack)
+        rows.push(["stack", `- ${report.noStack}`]);
     if (stack) {
         rows.push([
             "stack",
             stack.state === "absent"
-                ? `- not created under ${stack.home}: run nylorun up`
+                ? `- ${stack.name} not created under ${stack.home}: run nylorun up`
                 : stack.state === "stopped"
-                    ? `- stopped (project ${stack.project}): run nylorun up`
+                    ? `- ${stack.name} stopped (Compose project ${stack.project}): run nylorun up`
                     : stack.runtime.healthy
-                        ? `✓ running (project ${stack.project})`
-                        : `✗ running, but the Runtime does not answer: see nylorun status and nylorun logs runtime`,
+                        ? `✓ ${stack.name} running (Compose project ${stack.project})`
+                        : `✗ ${stack.name} running, but the Runtime does not answer: see nylorun status and nylorun logs runtime`,
         ]);
         if (stack.state === "running") {
             rows.push([
@@ -66,6 +82,19 @@ export async function doctorStack(options) {
                     ? `✓ ${stack.runtime.url ?? "?"} · ${stack.runtime.version ?? "?"}`
                     : `✗ ${stack.runtime.url ?? "?"} not answering`,
             ]);
+            rows.push([
+                "gateway",
+                stack.gateway.healthy
+                    ? `✓ ${stack.gateway.state} · combined packing (runtime: core,loop; gateway: gates)`
+                    : `✗ ${stack.gateway.state}: model calls fail; see nylorun logs gateway`,
+            ]);
+            if (stack.tenant)
+                rows.push([
+                    "tenant",
+                    stack.tenant.state === "open"
+                        ? `✓ ${stack.tenant.id ?? "?"} open`
+                        : `✗ ${stack.tenant.id ?? "?"} unavailable${stack.tenant.cause ? `: ${stack.tenant.cause.code}: ${stack.tenant.cause.repair}` : " (opening)"}`,
+                ]);
             rows.push(["studio", `${stack.studio.url ?? "?"} · ${stack.studio.state}`]);
         }
     }

package/dist/project/derived-key.d.ts

@@ -0,0 +1,8 @@
+/** The derived principal a Project uses; the stack's Runtime registers it on its Tenant. */
+export declare const PROJECT_PRINCIPAL_ID = "project";
+/**
+ * Key of a derived principal on the stack's Tenant, from the admin key. A copy of
+ * `deriveTenantKey` in `@nylorun/admin` (nylorun depends on `@nylorun/core` only); both are
+ * tested against the same fixed vector.
+ */
+export declare function deriveTenantKey(adminKey: string, tenantId: string, principalId: string): string;

package/dist/project/derived-key.js

@@ -0,0 +1,18 @@
+import { createHmac } from "node:crypto";
+/** The derived principal a Project uses; the stack's Runtime registers it on its Tenant. */
+export const PROJECT_PRINCIPAL_ID = "project";
+/**
+ * Key of a derived principal on the stack's Tenant, from the admin key. A copy of
+ * `deriveTenantKey` in `@nylorun/admin` (nylorun depends on `@nylorun/core` only); both are
+ * tested against the same fixed vector.
+ */
+export function deriveTenantKey(adminKey, tenantId, principalId) {
+    const message = Buffer.concat([
+        Buffer.from("nylorun/principal/v1", "utf8"),
+        Buffer.from([0]),
+        Buffer.from(principalId, "utf8"),
+        Buffer.from([0]),
+        Buffer.from(tenantId, "utf8"),
+    ]);
+    return createHmac("sha256", Buffer.from(adminKey, "utf8")).update(message).digest("hex");
+}

package/dist/project/link.d.ts

@@ -1,6 +1,34 @@
 /**
- * The linked Project's Tenant id, read from `.nylorun/link.json`, or undefined
- * outside a linked Project. nylorun only reads the link: `@nylorun/cli` writes
- * it when it creates or chooses a Tenant.
+ * The Project link (`.nylorun/link.json`) and credentials (`.nylorun/credentials.json`).
+ * `nylorun start` writes both, format 2: the stack the Project uses, its URL and Host id, and
+ * the Tenant id as information (nothing selects a Tenant). Formats 0 and 1 named a Tenant on a
+ * multi-Tenant Host of an older Runtime.
  */
-export declare function linkedTenantId(cwd?: string): Promise<string | undefined>;
+export interface ProjectLink {
+    format: 0 | 1 | 2;
+    /** The local stack (format 2). */
+    stack?: string;
+    hostUrl: string;
+    hostId: string;
+    tenantId?: string;
+}
+export declare function linkPath(projectRoot: string): string;
+export declare function credentialsPath(projectRoot: string): string;
+/** The Project's link, or undefined when it has none. An unreadable link is an error. */
+export declare function readProjectLink(projectRoot: string): Promise<ProjectLink | undefined>;
+export declare function writeProjectLink(projectRoot: string, link: {
+    stack: string;
+    hostUrl: string;
+    hostId: string;
+    tenantId: string;
+}): Promise<void>;
+/** The Project's application key and principal, or undefined when absent or unreadable. */
+export declare function readProjectCredentials(projectRoot: string): Promise<{
+    applicationKey: string;
+    principalId: string;
+} | undefined>;
+/** `.nylorun/credentials.json` (format 1, mode 0600). */
+export declare function writeProjectCredentials(projectRoot: string, credentials: {
+    applicationKey: string;
+    principalId: string;
+}): Promise<void>;