nylorun 0.3.0-beta → 0.4.0-beta

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # 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

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,66 +34,119 @@ npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the stack
 ## 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 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.
-
-`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 stack's first start, avoiding the ports other
+stacks 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 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
-`<Host root>/stack/.env`) may frame it. The default is Babai's
+`~/.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 limited to one Tenant with
+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`.
@@ -102,12 +160,29 @@ 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
 
@@ -115,11 +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 |
-| 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 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
@@ -127,9 +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 |
-| `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 |
+| `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>;

package/dist/project/link.js

@@ -1,21 +1,90 @@
-import { readFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { isTenantId } from "@nylorun/core/compatibility";
-import { findProjectRoot } from "./root.js";
-/**
- * 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.
- */
-export async function linkedTenantId(cwd = process.cwd()) {
-    const root = findProjectRoot(cwd);
-    if (!root)
-        return undefined;
+import { ProjectLinkFileSchema } from "@nylorun/core/contracts";
+import { CliError } from "../errors.js";
+export function linkPath(projectRoot) {
+    return join(projectRoot, ".nylorun", "link.json");
+}
+export function credentialsPath(projectRoot) {
+    return join(projectRoot, ".nylorun", "credentials.json");
+}
+/** The Project's link, or undefined when it has none. An unreadable link is an error. */
+export async function readProjectLink(projectRoot) {
+    let text;
+    try {
+        text = await readFile(linkPath(projectRoot), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        value = undefined;
+    }
+    const parsed = ProjectLinkFileSchema.safeParse(value);
+    if (!parsed.success)
+        throw new CliError(`Invalid or newer Project link at ${linkPath(projectRoot)}. Upgrade nylorun, or remove the file and run "npx nylorun start" again.`, 1);
+    const link = parsed.data;
+    return {
+        format: link.format,
+        ...(link.stack ? { stack: link.stack } : {}),
+        hostUrl: link.hostUrl.replace(/\/$/, ""),
+        hostId: link.hostId,
+        ...(link.tenantId ? { tenantId: link.tenantId } : {}),
+    };
+}
+async function writePrivate(path, value) {
+    const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
     try {
-        const link = JSON.parse(await readFile(join(root, ".nylorun", "link.json"), "utf8"));
-        return isTenantId(link.tenantId) ? link.tenantId : undefined;
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+        await rename(temporary, path);
+        await chmod(path, 0o600);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** `.nylorun/` mode 0700 with its own `.gitignore` of `*`; the Project's is never edited. */
+async function ensureProjectDir(projectRoot) {
+    const dir = join(projectRoot, ".nylorun");
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+    await writeFile(join(dir, ".gitignore"), "*\n", { mode: 0o600 });
+}
+export async function writeProjectLink(projectRoot, link) {
+    await ensureProjectDir(projectRoot);
+    await writePrivate(linkPath(projectRoot), {
+        format: 2,
+        stack: link.stack,
+        hostUrl: link.hostUrl.replace(/\/$/, ""),
+        hostId: link.hostId,
+        tenantId: link.tenantId,
+    });
+}
+/** The Project's application key and principal, or undefined when absent or unreadable. */
+export async function readProjectCredentials(projectRoot) {
+    try {
+        const value = JSON.parse(await readFile(credentialsPath(projectRoot), "utf8"));
+        return typeof value.applicationKey === "string" && typeof value.principalId === "string"
+            ? { applicationKey: value.applicationKey, principalId: value.principalId }
+            : undefined;
     }
     catch {
         return undefined;
     }
 }
+/** `.nylorun/credentials.json` (format 1, mode 0600). */
+export async function writeProjectCredentials(projectRoot, credentials) {
+    await ensureProjectDir(projectRoot);
+    await writePrivate(credentialsPath(projectRoot), {
+        format: 1,
+        applicationKey: credentials.applicationKey,
+        principalId: credentials.principalId,
+    });
+}