nylorun 0.3.0-beta → 0.5.0-beta

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # nylorun
 
+## 0.5.0-beta
+
+### Minor Changes
+
+- f96fe32: **Studio reports anonymous page views, unless you opt out.** Studio sends page views to Google Analytics with every Tenant, agent and session id replaced by `:id` and the query dropped; nothing sent to agents is collected. `nylorun start` says so once, and passes the measurement id to the Studio container as `NYLORUN_STUDIO_ANALYTICS_ID`. Turn it off with `nylorun telemetry disable`, `NYLORUN_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`; it is always off in CI, inside an embedding app, and when the browser sends Do Not Track or Global Privacy Control.
+- 4b9906f: **Breaking: "Tenant" replaces "stack", and `nylorun start` works anywhere.** Each local installation holds one Tenant, and its name is the Tenant's name, so help, output, errors and docs say Tenant. See MIGRATION.md.
+
+  - **Breaking (`nylorun`): selection.** Every command acts on the Tenant `--tenant <name>` names (replaces `--name`, which is removed), else `NYLORUN_TENANT` (replaces `NYLORUN_STACK`), else the Project link's `tenant`; `start` in a project names a new one after the project directory. Outside a project, or with `start --no-link`, commands act on the Tenant `default`. In a project without a link, commands other than `start` exit 2 and list the machine's Tenants. A name starting with `tn_` (a Tenant id) is refused.
+  - **Breaking (`nylorun`): files.** Host roots are under `~/.nylorun/tenants/<name>/` (was `~/.nylorun/stacks/<name>/`) with `tenant.json` (was `stack.json`); the `.env` key is `NYLORUN_TENANT_NAME` (was `NYLORUN_STACK_NAME`); `NYLORUN_COMPOSE_PROJECT` replaces `NYLORUN_STACK_PROJECT`. Compose projects stay `nylorun-<name>`. Every command first moves 0.4 Host roots from `~/.nylorun/stacks/` to `~/.nylorun/tenants/` (renaming `stack.json` and the `.env` key), so they keep their volumes and keys. `nylorun ls` lists only directories with `tenant.json`.
+  - **Breaking (`nylorun`): removed.** `nylorun legacy` and all handling of the single stack of releases before 0.4; the hidden `nylorun stack <cmd>` alias; `nylorun doctor stack|runtime`. Output says Tenant: `ls` prints `TENANT` and JSON `{ "tenants": [...] }`, `status` prints the Tenant id on its own line, and `doctor`'s row is `tenant`.
+  - **Breaking: Project link format 3.** `.nylorun/link.json` is `{ "format": 3, "tenant", "tenantId", "hostUrl", "hostId" }`; `tenant` replaces `stack`. `@nylorun/agents`, `@nylorun/cli` and `@nylorun/admin` refuse an older link and name `npx nylorun start`, which rewrites it. `@nylorun/core`'s `ProjectLinkFileSchema` parses formats 0–3 with `tenant`.
+  - **Breaking (`@nylorun/admin`):** `createAdmin({ tenant })` replaces `{ stack }`, `tenantHostRoot(name)` replaces `stackHostRoot(name)`, and local resolution reads `NYLORUN_TENANT` and the link's `tenant`.
+  - `@nylorun/cli`: `status` and `endpoints` drop the `stack` line and JSON key; messages say Tenant. `@nylorun/agents`: a Runtime too old for the client says "update the Runtime (npx nylorun@latest start)". `@nylorun/studio`: setup hints say Tenant. `@nylorun/create-agent`: the next steps describe `npx nylorun@beta start` as this project's Tenant and its link.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [4b9906f]
+  - @nylorun/core@0.11.0-beta
+
+## 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

package/README.md

@@ -1,18 +1,23 @@
 # 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 Tenants: the Runtime and Studio, in Docker
+Compose, one Tenant 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 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:
-[runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
+A local Tenant is one installation: one Runtime with its own Postgres, Restate
+and S2, serving exactly that Tenant, and its name is the Tenant's name.
+`nylorun start` in a project creates the project's Tenant (the Runtime creates
+it on its first start) and links the project to it; anywhere else, it starts
+the Tenant `default`. Projects that must not share agents, credentials or
+history run separate Tenants. 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
 24 or newer, and Docker with Compose v2 ([Docker
@@ -23,91 +28,171 @@ another engine). On Windows, install them inside
 supported.
 
 ```sh
-npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the stack's health
+npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the Tenant's health
 ```
 
 ## Commands
 
 ```sh
-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
-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 doctor [--json]            # prerequisites and stack health
+nylorun up|start [--tenant <name>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]
+                                   # create (first run) and start the Tenant; link the project; print the URLs; open Studio signed in
+nylorun down|stop [--tenant <name>]   # stop the containers; keep volumes
+nylorun status [--tenant <name>] [--json]   # the Tenant, its Host root and id, services, endpoints, Runtime health
+nylorun logs [service] [--tenant <name>] [-f] [--tail <n>]   # postgres, restate, s2, gateway, runtime, studio
+nylorun studio [--tenant <name>] [--no-open]   # sign a browser in to Studio on the Tenant; starts it if needed
+nylorun reset [--tenant <name>] [--yes]        # delete the Tenant's volumes, Tenant directory and vault key; the next start creates it anew
+nylorun ls [--json]                # the Tenants on this machine
+nylorun delete <tenant> --yes      # remove a Tenant: containers, volumes, Host root and vault key
+nylorun doctor [--json]            # prerequisites and the Tenant's health
+nylorun telemetry [status|enable|disable]   # Studio's anonymous usage analytics
 ```
 
 `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`.
-
-## 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`);
+stops the containers and keeps the volumes, so no Tenant data is lost. Removed
+commands exit 2 naming the replacement: `nylorun dev`, `nylorun configure`,
+`nylorun status --env` and `nylorun doctor sandbox`.
+
+## Tenants
+
+Every command acts on one Tenant, chosen in this order:
+
+1. `--tenant <name>`;
+2. `NYLORUN_TENANT`;
+3. the Tenant in the project's link (`.nylorun/link.json`, found from the
+   working directory upwards);
+4. for `start` in a project: the project directory's name, lowercased, with
+   characters outside `[a-z0-9_-]` as `-`, and a suffix (`-2`, `-3`, …) when a
+   Tenant of that name was created for another project directory;
+5. outside a project, or `start --no-link`: the Tenant `default`.
+
+In a project without a link, the commands other than `start` exit 2 and list
+the Tenants on this machine. A name is lowercase letters, digits, `-` and `_`;
+a Tenant id (`tn_…`) is refused: pass the Tenant's name (`nylorun ls` lists
+them).
+
+Each Tenant has its own Host root `~/.nylorun/tenants/<name>/`, Compose project
+`nylorun-<name>` (`NYLORUN_COMPOSE_PROJECT` overrides it), volumes, network and
+ports. `NYLORUN_HOME` replaces the whole Host root (the Tenant's name then
+comes from its `tenant.json`, the project directory or the Host root's own
+name). nylorun 0.4 kept Host roots in `~/.nylorun/stacks/`: the first command
+of this release moves them to `~/.nylorun/tenants/`, keeping their Compose
+projects and volumes.
+
+A Tenant 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 Tenant is open
+(`/v1/admin/status`), then writes, in a `.nylorun/` directory (mode 0700, with
+its own `.gitignore` of `*`):
+
+- `link.json`: `{ "format": 3, "tenant", "tenantId", "hostUrl", "hostId" }`.
+  `tenant` is the local Tenant's name; 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 Tenant's admin key, and its id.
+
+Later starts reuse the Tenant and rewrite the link only when the Tenant's name,
+URL, Host or id 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 containers.
+
+A fresh clone or a second worktree has no link: `nylorun start` there creates a
+new Tenant, or `nylorun start --tenant <name>` attaches it to an existing one so
+both share it. `--no-link` starts a Tenant without linking the working
+directory (scripts). A link of an older nylorun (format 0 to 2) counts as no
+link: `start` replaces it.
+
+The Runtime registers the derived principals of `NYLORUN_DERIVED_PRINCIPALS`
+(comma-separated, from the environment of `nylorun start`, kept in the Tenant's
+`.env`) when it creates the Tenant; `project` is always among them.
+
+## The containers
+
+`nylorun start` writes `compose.yaml` and `.env` (mode 0600) under
+`~/.nylorun/tenants/<name>/docker/` on the first run and reuses them after that: `postgres`,
+`restate`, `s2`, `gateway`, `runtime` and `studio`. Postgres initialises the
+Tenant'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.
-
-`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
+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 Tenant's first start, avoiding the ports other
+Tenants keep, and kept in its `.env`.
+
+`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 Tenant's page 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
-`<Host root>/stack/.env`) may frame it. The default is Babai's
+`~/.nylorun/tenants/<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 limited to one Tenant with
+The app's backend mints a single-use login token for the 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`.
 
+### Telemetry
+
+Studio reports anonymous page views to Google Analytics, so we can see which
+parts of it are used. A page view carries the route's shape only: every Tenant,
+agent and session id becomes `:id` (`/tenants/:id/agents/:id/sessions/:id`)
+and the query is dropped. Nothing you send to agents, no names, keys or
+responses, and no Google signals or ad personalization are collected. Studio
+loads no analytics inside an embedding app, or when the browser sends Do Not
+Track or Global Privacy Control.
+
+It is on by default, and `nylorun start` says so the first time. Turn it off on
+this machine with `nylorun telemetry disable` (kept in
+`~/.nylorun/telemetry.json`), or for one start with `NYLORUN_TELEMETRY_DISABLED=1`
+or `DO_NOT_TRACK=1`. It is always off when `CI` is set. `nylorun start` decides
+on every start and writes the result to `NYLORUN_STUDIO_ANALYTICS_ID` in
+`docker/.env` (empty when off); `nylorun telemetry` reports the current choice.
+
 ## 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
+default names one (`PUT /v1/tenant/sandbox`). A local Tenant 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/tenants/<name>/`, or `NYLORUN_HOME`. It is
+bind-mounted into the Runtime and Studio containers, and holds `tenant.json`
+(`{ "format": 1, "name", "project"? }`: the Tenant'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 its Postgres, Restate and S2 volumes.
+
+`nylorun reset` deletes the selected Tenant's volumes, `tenant/` and `keys/`, and keeps
+its files and ports; the next start creates the Tenant anew (with a new id) and
+relinks the project. `nylorun delete <tenant> --yes` removes the Tenant's
+containers, volumes and Host root: the vault key (KEK) and all its data go with it.
 
 ## Exit codes
 
@@ -115,11 +200,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 Tenant selected, or `delete` without `--yes`), or a removed or moved command |
+| 3 | `status`: the Runtime is not answering; `stop`/`logs`: no Tenant yet; `delete`: no such Tenant |
 | 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 |
+| 5 | `up`/`start`/`studio`: this nylorun pins a Runtime older than the one that last ran the Tenant; update nylorun, or `start --allow-downgrade` |
+| 7 | The containers, the Tenant or Studio did not become ready (an unavailable Tenant's cause is printed) |
 | 130 / 143 | SIGINT / SIGTERM |
 
 ## Troubleshooting
@@ -127,9 +212,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 |
-| `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` |
+| `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 |
+| `Tenant … is unavailable` (exit 7) | Follow the repair it names; `nylorun logs runtime` |
+| Port conflict | Change `NYLORUN_PORT` / `NYLORUN_STUDIO_PORT` in `~/.nylorun/tenants/<name>/docker/.env` |
 | Logs | `nylorun logs runtime -f` |
 | Studio login expired | `nylorun studio` |
 

package/dist/cli.js

@@ -2,26 +2,31 @@
 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|doctor|telemetry>
 
-Local stack (Docker Compose):
+Local Tenants (Docker Compose), one per project:
 ${stackUsage}
-  doctor [--json]                     check Node, Docker and Compose v2, and the stack's health
+  doctor [--json]                     check Node, Docker and Compose v2, and the Tenant's health
+  telemetry [status|enable|disable]   Studio's anonymous usage analytics (on unless disabled,
+                                      NYLORUN_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 or CI)
 
-nylorun sets up and runs the local stack. Tenants, Project links and model
-providers belong to the Runtime client: npx @nylorun/cli --help`;
+A command acts on the Tenant --tenant or NYLORUN_TENANT names, else the linked project's,
+else (outside a project) the default Tenant; NYLORUN_HOME sets its Host root
+(default ~/.nylorun/tenants/<name>).
+
+nylorun sets up and runs local Tenants. "nylorun start" in a project creates the
+project's Tenant and the Project link; anywhere else, it starts the default Tenant.
+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 Tenant and the Project link), then your project's `npm run dev`.",
     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.",
-    runtime: "nylorun runtime was removed: the local Runtime runs in the Docker Compose stack. Use nylorun up|down|status|logs.",
+    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 Docker Compose. 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.";
+const LOCAL_UI_REMOVED = "--local-ui was removed: Studio runs in its own container. Run nylorun studio.";
 const usageError = (message) => new CliError(message, 2);
 async function main() {
     const [command, ...args] = process.argv.slice(2);
@@ -37,31 +42,30 @@ 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)) {
         process.exitCode = await stackCommand(command, args, baselineEnv());
         return;
     }
-    // `nylorun stack <command>`: the Wave 1 spelling, kept as a hidden alias.
-    if (command === "stack") {
-        const [name, ...rest] = args;
-        if (!isStackCommand(name))
-            throw usageError(usage);
-        process.exitCode = await stackCommand(name, rest, baselineEnv());
+    if (command === "telemetry") {
+        const { telemetryCommand } = await import("./telemetry.js");
+        const { defaultNylorunRoot } = await import("./stack/stacks.js");
+        process.exitCode = await telemetryCommand(args, {
+            nylorunRoot: defaultNylorunRoot(),
+            env: baselineEnv(),
+            out: (line) => console.log(line),
+        });
         return;
     }
     if (command === "doctor") {
-        // `doctor stack` and `doctor runtime` are older spellings of `doctor`.
-        const options = args[0] === "stack" || args[0] === "runtime" ? args.slice(1) : args;
         if (args[0] === "sandbox")
             throw usageError(`nylorun doctor sandbox moved to the Runtime client: ${CLIENT} doctor sandbox`);
-        if (options.some((option) => option !== "--json"))
+        if (args.some((option) => option !== "--json"))
             throw usageError("Usage: nylorun doctor [--json]");
         const { doctorStack } = await import("./doctor.js");
-        process.exitCode = await doctorStack({ json: options.includes("--json"), env: baselineEnv() });
+        process.exitCode = await doctorStack({ json: args.includes("--json"), env: baselineEnv() });
         return;
     }
     throw usageError(usage);

package/dist/doctor.d.ts

@@ -6,18 +6,20 @@ export interface StackDoctorReport {
     };
     docker: Check;
     compose?: Check;
-    stack?: Pick<StackStatus, "project" | "home" | "state" | "runtime" | "studio">;
+    tenant?: Pick<StackStatus, "name" | "project" | "home" | "state" | "runtime" | "tenant" | "studio" | "gateway">;
+    /** Why no Tenant was checked: none is selected here (a project without a link). */
+    noTenant?: string;
 }
 /**
- * `nylorun doctor`: check the prerequisites of the local stack (Node 24+,
- * Docker, Compose v2) and, when they pass, the stack's health. Prints the fix
+ * `nylorun doctor`: check the prerequisites of a local Tenant (Node 24+,
+ * Docker, Compose v2) and, when they pass, the Tenant's health. Prints the fix
  * for each problem and returns 1 when a prerequisite is missing or a running
- * stack is unhealthy; installs and starts nothing.
+ * Tenant is unhealthy; installs and starts nothing.
  */
 export declare function doctorStack(options: {
     json: boolean;
     env?: Readonly<Record<string, string | undefined>>;
-    /** Stack dependencies (tests). */
+    /** Command dependencies (tests). */
     deps?: StackDeps;
     log?: (line: string) => void;
 }): Promise<number>;

package/dist/doctor.js

@@ -1,11 +1,12 @@
+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. */
+/** Oldest Node nylorun and the developer's application run on. */
 const MIN_NODE_MAJOR = 24;
 /**
- * `nylorun doctor`: check the prerequisites of the local stack (Node 24+,
- * Docker, Compose v2) and, when they pass, the stack's health. Prints the fix
+ * `nylorun doctor`: check the prerequisites of a local Tenant (Node 24+,
+ * Docker, Compose v2) and, when they pass, the Tenant's health. Prints the fix
  * for each problem and returns 1 when a prerequisite is missing or a running
- * stack is unhealthy; installs and starts nothing.
+ * Tenant is unhealthy; installs and starts nothing.
  */
 export async function doctorStack(options) {
     const log = options.log ?? ((line) => console.log(line));
@@ -17,17 +18,30 @@ 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.tenant = {
+                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.noTenant = error.message;
+        }
     }
-    const stackBroken = report.stack?.state === "running" && !report.stack.runtime.healthy;
-    const failed = !nodeOk || !checks.docker.ok || checks.compose?.ok === false || stackBroken;
+    const broken = report.tenant?.state === "running" &&
+        (!report.tenant.runtime.healthy ||
+            !report.tenant.gateway.healthy ||
+            report.tenant.tenant?.cause !== undefined);
+    const failed = !nodeOk || !checks.docker.ok || checks.compose?.ok === false || broken;
     if (options.json) {
         log(JSON.stringify(report, null, 2));
         return failed ? 1 : 0;
@@ -47,26 +61,41 @@ export async function doctorStack(options) {
         ["docker", line(checks.docker)],
         ["compose", line(checks.compose)],
     ];
-    const stack = report.stack;
-    if (stack) {
+    const local = report.tenant;
+    if (report.noTenant)
+        rows.push(["tenant", `- ${report.noTenant}`]);
+    if (local) {
         rows.push([
-            "stack",
-            stack.state === "absent"
-                ? `- not created under ${stack.home}: run nylorun up`
-                : stack.state === "stopped"
-                    ? `- stopped (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`,
+            "tenant",
+            local.state === "absent"
+                ? `- ${local.name} not created under ${local.home}: run nylorun up`
+                : local.state === "stopped"
+                    ? `- ${local.name} stopped (Compose project ${local.project}): run nylorun up`
+                    : local.runtime.healthy
+                        ? `✓ ${local.name} running (Compose project ${local.project})`
+                        : `✗ ${local.name} running, but the Runtime does not answer: see nylorun status and nylorun logs runtime`,
         ]);
-        if (stack.state === "running") {
+        if (local.state === "running") {
             rows.push([
                 "runtime",
-                stack.runtime.healthy
-                    ? `✓ ${stack.runtime.url ?? "?"} · ${stack.runtime.version ?? "?"}`
-                    : `✗ ${stack.runtime.url ?? "?"} not answering`,
+                local.runtime.healthy
+                    ? `✓ ${local.runtime.url ?? "?"} · ${local.runtime.version ?? "?"}`
+                    : `✗ ${local.runtime.url ?? "?"} not answering`,
+            ]);
+            rows.push([
+                "gateway",
+                local.gateway.healthy
+                    ? `✓ ${local.gateway.state} · combined packing (runtime: core,loop; gateway: gates)`
+                    : `✗ ${local.gateway.state}: model calls fail; see nylorun logs gateway`,
             ]);
-            rows.push(["studio", `${stack.studio.url ?? "?"} · ${stack.studio.state}`]);
+            if (local.tenant)
+                rows.push([
+                    "tenant id",
+                    local.tenant.state === "open"
+                        ? `✓ ${local.tenant.id ?? "?"} open`
+                        : `✗ ${local.tenant.id ?? "?"} unavailable${local.tenant.cause ? `: ${local.tenant.cause.code}: ${local.tenant.cause.repair}` : " (opening)"}`,
+                ]);
+            rows.push(["studio", `${local.studio.url ?? "?"} · ${local.studio.state}`]);
         }
     }
     const width = Math.max(...rows.map(([key]) => key.length)) + 2;

package/dist/home.d.ts

@@ -1,5 +1,5 @@
 /**
- * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. The stack
+ * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. Compose
  * bind-mounts it into the Runtime and Studio containers, and `@nylorun/admin`
  * reads `host.json` and the admin key from it.
  */

package/dist/home.js

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 /**
- * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. The stack
+ * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. Compose
  * bind-mounts it into the Runtime and Studio containers, and `@nylorun/admin`
  * reads `host.json` and the admin key from it.
  */