nylorun 0.7.0-beta → 0.9.0-beta

package/dist/stack/commands.js

@@ -3,8 +3,7 @@ import { mkdir, readFile, rm } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import { compareVersions, PROTOCOL_HEADER, PROTOCOL_VERSION, } from "@nylorun/core/compatibility";
 import { CliError } from "../errors.js";
-import { deriveTenantKey, PROJECT_PRINCIPAL_ID } from "../project/derived-key.js";
-import { readProjectCredentials, readProjectLink, writeProjectCredentials, writeProjectLink, } from "../project/link.js";
+import { credentialsPath, readCredentialsFile, readProjectCredentials, readProjectLink, writeProjectCredentials, writeProjectLink, } from "../project/link.js";
 import { findProjectRoot } from "../project/root.js";
 import { seedTenant } from "../project/seed.js";
 import { readTelemetry, STUDIO_ANALYTICS_ID, TELEMETRY_NOTICE, telemetryDecision, writeTelemetry, } from "../telemetry.js";
@@ -15,13 +14,28 @@ import { stackPaths } from "./paths.js";
 import { prepareStack, readStackEnv } from "./prepare.js";
 import { assertTenantName, chooseTenantName, DEFAULT_TENANT, defaultNylorunRoot, listTenants, moveStackRoots, readTenantRecord, removeOldProxy, sanitizeTenantName, tenantRoot, tenantsDir, writeTenantRecord, } from "./stacks.js";
 import { mintStudioLogin, studioOrigin } from "./studio-login.js";
-export const STACK_SERVICES = ["postgres", "restate", "s2-lite", "gateway", "runtime", "studio"];
-const CORE_SERVICES = ["postgres", "restate", "s2-lite", "gateway", "runtime"];
-export const stackUsage = `  up|start [--tenant <name>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]
+import { CLI_KEY_ID, hostKey, keyAuthenticates, PROJECT_KEY_ID, } from "./operator-keys.js";
+export const STACK_SERVICES = [
+    "postgres",
+    "restate",
+    "s2-lite",
+    "rustfs",
+    "gateway",
+    "runtime",
+    "harness",
+    "studio",
+];
+const CORE_SERVICES = ["postgres", "restate", "s2-lite", "rustfs", "gateway", "runtime", "harness"];
+/** The services `start` waits for: the harness only while it runs turns (`NYLORUN_HARNESS=remote`). */
+function coreServices(harness) {
+    return CORE_SERVICES.filter((service) => service !== "harness" || harness === "remote");
+}
+export const stackUsage = `  up|start [--tenant <name>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset] [--restate-ui]
                                       start the project's Tenant, creating it and the Project link (.nylorun/link.json,
                                       credentials.json) on the first run; print the Runtime and Studio URLs and open Studio
                                       signed in (in a terminal). --tenant attaches to (or creates) a named Tenant; --no-link
-                                      starts the default Tenant (or --tenant's) without linking the current directory
+                                      starts the default Tenant (or --tenant's) without linking the current directory;
+                                      --restate-ui (or NYLORUN_RESTATE_UI=1) publishes Restate's UI on loopback for debugging
   down|stop [--tenant <name> | --all] stop the Tenant's containers (--all: every Tenant's); keep volumes
   status [--tenant <name>] [--json]   the Tenant, its id, services, endpoints and Runtime health
   logs [service] [--tenant <name>] [-f] [--tail <n>]
@@ -207,8 +221,8 @@ async function waitForHealth(ctx, runtimeUrl, hostId) {
         await sleep(ctx.deps.pollMs ?? 500);
     }
 }
-/** `/v1/admin/status`'s Tenant on the operator listener; undefined when it does not answer. */
-async function fetchTenant(deps, adminUrl, adminKey) {
+/** `/v1/admin/status` on the operator listener; undefined when it does not answer. */
+async function fetchAdminStatus(deps, adminUrl, adminKey) {
     if (!adminKey)
         return undefined;
     try {
@@ -223,20 +237,32 @@ async function fetchTenant(deps, adminUrl, adminKey) {
         });
         if (!response.ok)
             return undefined;
-        const tenant = (await response.json()).tenant;
+        const body = (await response.json());
+        const tenant = body.tenant;
         if (!tenant || (tenant.state !== "open" && tenant.state !== "unavailable"))
             return undefined;
+        const harness = body.aggregate?.harness;
         return {
-            id: typeof tenant.id === "string" ? tenant.id : null,
-            name: typeof tenant.name === "string" ? tenant.name : null,
-            state: tenant.state,
-            ...(tenant.cause ? { cause: tenant.cause } : {}),
+            tenant: {
+                id: typeof tenant.id === "string" ? tenant.id : null,
+                name: typeof tenant.name === "string" ? tenant.name : null,
+                state: tenant.state,
+                ...(tenant.cause ? { cause: tenant.cause } : {}),
+            },
+            ...((harness?.mode === "remote" || harness?.mode === "in-process") &&
+                typeof harness.connected === "number"
+                ? { harness: { mode: harness.mode, connected: harness.connected } }
+                : {}),
         };
     }
     catch {
         return undefined;
     }
 }
+/** `/v1/admin/status`'s Tenant on the operator listener; undefined when it does not answer. */
+async function fetchTenant(deps, adminUrl, adminKey) {
+    return (await fetchAdminStatus(deps, adminUrl, adminKey))?.tenant;
+}
 /** Why the Tenant is unavailable, with the repair the Runtime names. */
 function tenantCauseMessage(ctx, tenant) {
     const cause = tenant.cause;
@@ -366,11 +392,10 @@ async function bringUp(ctx, options) {
         runtimeVersion: overridden ? undefined : deps.runtimeVersion,
         ports: deps.ports,
         reserved: await reservedPorts(ctx),
-        ...(deps.env.NYLORUN_DERIVED_PRINCIPALS?.trim()
-            ? { derivedPrincipals: deps.env.NYLORUN_DERIVED_PRINCIPALS }
-            : {}),
         ...(options.studioEmbedOrigins ? { studioEmbedOrigins: options.studioEmbedOrigins } : {}),
         ...(analytics ? { studioAnalyticsId: STUDIO_ANALYTICS_ID } : {}),
+        ...(options.sandboxes !== undefined ? { sandboxes: options.sandboxes } : {}),
+        ...(options.restateUi !== undefined ? { restateUi: options.restateUi } : {}),
     });
     if (analytics && options.studio && telemetry.noticeShown === undefined) {
         deps.err(TELEMETRY_NOTICE);
@@ -384,15 +409,24 @@ async function bringUp(ctx, options) {
         deps.err(`Created Tenant ${ctx.name} under ${ctx.paths.root} (Runtime port ${prepared.env.runtimePort}, Studio port ${prepared.env.studioPort}).`);
     const runtimeUrl = `http://${STACK_CLIENT_HOST}:${prepared.env.runtimePort}`;
     const adminUrl = `http://${STACK_CLIENT_HOST}:${prepared.env.adminPort}`;
-    const up = await deps.docker.stream(composeArgs(ctx, "up", "--detach", "--wait", "--wait-timeout", "300", ...CORE_SERVICES));
+    const up = await deps.docker.stream(
+    // --remove-orphans: a service this start's file no longer has (the harness after a rollback
+    // to NYLORUN_HARNESS=in-process, sandboxes after disable) is removed, not left running.
+    composeArgs(ctx, "up", "--detach", "--wait", "--wait-timeout", "300", "--remove-orphans", ...coreServices(prepared.env.harness)));
     if (up !== 0) {
         // A Runtime whose Tenant cannot open fails readiness; its status names the cause.
         const tenant = await fetchTenant(deps, adminUrl, prepared.adminKey);
         if (tenant?.cause)
             throw new CliError(tenantCauseMessage(ctx, tenant), 7);
-        throw new CliError(`docker compose up failed (exit ${up}). See "nylorun logs runtime", "nylorun logs gateway" and "nylorun status".`, 7);
+        throw new CliError(`docker compose up failed (exit ${up}). See "nylorun logs runtime", "nylorun logs gateway", "nylorun logs harness" and "nylorun status".`, 7);
     }
     await waitForHealth(ctx, runtimeUrl, prepared.host.hostId);
+    // Without --wait: a cluster that is down must not fail the start; sessions refuse pods.
+    if (prepared.env.sandboxes) {
+        const sandboxes = await deps.docker.stream(composeArgs(ctx, "up", "--detach", "sandboxes"));
+        if (sandboxes !== 0)
+            deps.err(`Warning: the sandboxes service did not start. See "nylorun logs sandboxes".`);
+    }
     let studioStarted = false;
     if (options.studio) {
         const studio = await deps.docker.stream(composeArgs(ctx, "up", "--detach", "--wait", "--wait-timeout", "120", "studio"));
@@ -408,6 +442,9 @@ async function bringUp(ctx, options) {
         studioUrl: studioOrigin(prepared.env.studioPort),
         studioStarted,
         adminKey: prepared.adminKey,
+        ...(prepared.env.restateUi
+            ? { restateUrl: `http://${STACK_CLIENT_HOST}:${prepared.env.restatePort}` }
+            : {}),
     };
 }
 const errorText = (error) => (error instanceof Error ? error.message : String(error));
@@ -447,13 +484,17 @@ async function openLogin(ctx, login) {
 }
 /**
  * Link the project to the Tenant: `.nylorun/link.json` (format 3) and
- * `.nylorun/credentials.json` with the key of the derived principal `project`. The link is
- * rewritten only when it is older, or the Tenant's name, URL, Host or id changed; a new link
- * seeds the Tenant from the project's `.env`.
+ * `.nylorun/credentials.json`. The link is rewritten only when it is older, or the Tenant's
+ * name, URL, Host or id changed; a new link seeds the Tenant from the project's `.env`.
+ *
+ * The credentials file is kept while its key still reaches the Tenant (one authenticated
+ * read). Otherwise it gets the operator key `project` (F9 I1): the one the Host root keeps for
+ * the projects linked to this Tenant (`project-credentials.json`), or a new one put through
+ * the Admin API. Every checkout linked to the Tenant shares it, so linking one never rotates
+ * another's key.
  */
 async function linkProject(ctx, started, tenantId) {
     const { deps, projectDir, link } = ctx;
-    const applicationKey = deriveTenantKey(started.adminKey, tenantId, PROJECT_PRINCIPAL_ID);
     const fresh = link?.format !== 3 ||
         link.tenant !== ctx.name ||
         link.hostUrl !== started.runtimeUrl ||
@@ -466,14 +507,37 @@ async function linkProject(ctx, started, tenantId) {
             hostId: started.hostId,
             tenantId,
         });
-    const credentials = await readProjectCredentials(projectDir);
-    if (fresh ||
-        credentials?.applicationKey !== applicationKey ||
-        credentials.principalId !== PROJECT_PRINCIPAL_ID)
+    const existing = await readProjectCredentials(projectDir);
+    const admin = {
+        fetch: deps.fetch,
+        adminUrl: started.adminUrl,
+        adminKey: started.adminKey,
+    };
+    const keyOptions = {
+        admin,
+        runtimeUrl: started.runtimeUrl,
+        id: PROJECT_KEY_ID,
+        file: ctx.paths.projectCredentials,
+        lock: ctx.paths.keysLock,
+    };
+    let applicationKey;
+    if (existing && (await keyAuthenticates(deps.fetch, started.runtimeUrl, existing.applicationKey))) {
+        applicationKey = existing.applicationKey;
+        // A project key from before operator keys becomes the one the Host root keeps.
+        if (existing.principalId === PROJECT_KEY_ID &&
+            (await readCredentialsFile(ctx.paths.projectCredentials))?.applicationKey !== applicationKey)
+            await hostKey({ ...keyOptions, adopt: existing });
+    }
+    else {
+        const key = await hostKey(keyOptions);
+        applicationKey = key.applicationKey;
         await writeProjectCredentials(projectDir, {
-            applicationKey,
-            principalId: PROJECT_PRINCIPAL_ID,
+            applicationKey: key.applicationKey,
+            principalId: key.principalId,
         });
+        if (existing && !fresh)
+            deps.err(`Replaced the project's key, which no longer reaches Tenant ${ctx.name} (.nylorun/credentials.json).`);
+    }
     if (!fresh)
         return;
     deps.err(`Linked ${projectDir} to Tenant ${ctx.name} (.nylorun/link.json, .nylorun/credentials.json).`);
@@ -492,7 +556,7 @@ async function linkProject(ctx, started, tenantId) {
         deps.err(`Warning: could not seed the Tenant from .env (${error instanceof Error ? error.message : String(error)}). Set the model in Studio or with "npx @nylorun/cli configure".`);
     }
 }
-const START_USAGE = "nylorun start [--tenant <name>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]";
+const START_USAGE = "nylorun start [--tenant <name>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset] [--restate-ui]";
 async function start(deps, args) {
     const flags = parseStackFlags(args, {
         booleans: [
@@ -501,6 +565,7 @@ async function start(deps, args) {
             "--no-link",
             "--allow-downgrade",
             "--studio-embed-origin-reset",
+            "--restate-ui",
         ],
         values: ["--tenant"],
         lists: ["--studio-embed-origin"],
@@ -518,6 +583,7 @@ async function start(deps, args) {
     const started = await bringUp(ctx, {
         studio: !flags.booleans.has("--no-studio"),
         allowDowngrade: flags.booleans.has("--allow-downgrade"),
+        restateUi: flags.booleans.has("--restate-ui") || deps.env.NYLORUN_RESTATE_UI?.trim() === "1",
         ...(embedOrigins.length || resetEmbed
             ? { studioEmbedOrigins: { add: embedOrigins, reset: resetEmbed } }
             : {}),
@@ -527,6 +593,8 @@ async function start(deps, args) {
         await linkProject({ ...ctx, projectDir: ctx.projectDir }, started, tenant.id);
     deps.out(`Tenant    ${ctx.name}  (${tenant.id})`);
     deps.out(`Runtime   ${started.runtimeUrl}`);
+    if (started.restateUrl)
+        deps.out(`Restate   ${started.restateUrl}  (UI and admin, unauthenticated; for debugging)`);
     if (started.studioStarted) {
         deps.out(`Studio    ${started.studioUrl}`);
         if (opensBrowser(deps, flags)) {
@@ -607,8 +675,9 @@ async function stackStatus(ctx) {
         state: "absent",
         runtime: { healthy: false },
         studio: { state: "absent" },
-        restate: {},
+        restate: { published: false },
         gateway: { state: "absent", healthy: false },
+        harness: { mode: "remote", state: "absent", healthy: false },
         services: [],
     };
     if (!existsSync(ctx.paths.compose) || !existsSync(ctx.paths.env))
@@ -626,11 +695,14 @@ async function stackStatus(ctx) {
     const adminUrl = persisted.adminPort
         ? `http://${STACK_CLIENT_HOST}:${persisted.adminPort}`
         : runtimeUrl;
-    const tenant = healthy && adminUrl
-        ? await fetchTenant(ctx.deps, adminUrl, await readAdminKey(ctx.paths))
+    const answered = healthy && adminUrl
+        ? await fetchAdminStatus(ctx.deps, adminUrl, await readAdminKey(ctx.paths))
         : undefined;
+    const tenant = answered?.tenant;
     const studio = services.find((s) => s.service === "studio");
     const gateway = services.find((s) => s.service === "gateway");
+    const harness = services.find((s) => s.service === "harness");
+    const harnessMode = persisted.harness ?? "remote";
     return {
         ...base,
         state: services.some((s) => s.state === "running") ? "running" : "stopped",
@@ -649,13 +721,19 @@ async function stackStatus(ctx) {
                 ? { embedOrigins: persisted.studioFrameAncestors }
                 : {}),
         },
-        restate: persisted.restatePort
-            ? { url: `http://${STACK_CLIENT_HOST}:${persisted.restatePort}` }
-            : {},
+        restate: persisted.restatePort && persisted.restateUi
+            ? { url: `http://${STACK_CLIENT_HOST}:${persisted.restatePort}`, published: true }
+            : { published: false },
         gateway: {
             state: gateway ? [gateway.state, gateway.health].filter(Boolean).join(", ") : "absent",
             healthy: isUp(services, "gateway"),
         },
+        harness: {
+            mode: answered?.harness?.mode ?? harnessMode,
+            state: harness ? [harness.state, harness.health].filter(Boolean).join(", ") : "absent",
+            healthy: isUp(services, "harness"),
+            ...(answered?.harness ? { connected: answered.harness.connected } : {}),
+        },
         services,
     };
 }
@@ -700,8 +778,15 @@ async function status(deps, args) {
         if (result.studio.embedOrigins?.length)
             out(`Embeds      ${result.studio.embedOrigins.join(" ")}  (may show Studio in a frame)`);
         out(`Gateway     ${result.gateway.state} (the Model Gate; model calls fail while it is down)`);
-        if (result.restate.url)
-            out(`Restate UI  ${result.restate.url}`);
+        out(result.harness.mode === "remote"
+            ? `Harness     ${result.harness.state}, remote${result.harness.connected === undefined ? "" : `, ${result.harness.connected} connected`} (agent turns, MCP servers and workspaces; "nylorun logs harness")`
+            : `Harness     in-process (NYLORUN_HARNESS=in-process in .env: turns run in the runtime container)`);
+        out(result.restate.url
+            ? `Restate UI  ${result.restate.url}  (unauthenticated; published by --restate-ui)`
+            : `Restate UI  not published (nylorun start --restate-ui)`);
+        const sandboxes = result.services.find((s) => s.service === "sandboxes");
+        if (sandboxes)
+            out(`Sandboxes   ${[sandboxes.state, sandboxes.health].filter(Boolean).join(", ")} (see "nylorun sandbox status")`);
         out(`Services    ${STACK_SERVICES.map((name) => {
             const service = result.services.find((s) => s.service === name);
             const state = service
@@ -718,7 +803,7 @@ async function logs(deps, args) {
     if (flags.rest.length > 1)
         throw usageError(`Usage: ${usage}`);
     const service = flags.rest[0];
-    if (service !== undefined && !STACK_SERVICES.includes(service))
+    if (service !== undefined && ![...STACK_SERVICES, "sandboxes"].includes(service))
         throw usageError(`Unknown service ${service}. Usage: ${usage}`);
     const tail = flags.values.get("--tail");
     if (tail !== undefined && !/^\d+$/.test(tail))
@@ -865,6 +950,9 @@ async function runningStack(ctx, options) {
     const services = await composePs(ctx);
     if (!isUp(services, "runtime") || !isUp(services, "gateway"))
         return undefined;
+    // An older Tenant without the harness container is brought up again (remote is the default).
+    if ((persisted.harness ?? "remote") === "remote" && !isUp(services, "harness"))
+        return undefined;
     const studioUp = isUp(services, "studio");
     if (options.studio && !studioUp)
         return undefined;
@@ -907,6 +995,55 @@ async function ensureSelected(ctx, options) {
         started: !runtimeWasUp,
     };
 }
+async function runningSelected(deps, options) {
+    const ctx = await selectStack(deps, options);
+    requireStackFiles(ctx);
+    await dockerPreflight(deps.docker);
+    const running = await runningStack(ctx, { studio: false });
+    if (!running)
+        throw new CliError(`Tenant ${ctx.name} is not running. Run "nylorun start" first.`, 3);
+    const tenant = await fetchTenant(deps, running.adminUrl, running.adminKey);
+    if (!tenant?.id || tenant.state !== "open")
+        throw new CliError(`Tenant ${ctx.name} is not open. See "nylorun status".`, 7);
+    return {
+        ctx,
+        admin: {
+            name: ctx.name,
+            runtimeUrl: running.runtimeUrl,
+            paths: ctx.paths,
+            fetch: deps.fetch,
+            adminUrl: running.adminUrl,
+            adminKey: running.adminKey,
+        },
+    };
+}
+/**
+ * The selected Tenant's Admin API while it runs; exit 3 when it is not running, 7 when it is
+ * not open.
+ */
+export async function runningAdmin(deps, options = {}) {
+    return (await runningSelected(deps, options)).admin;
+}
+/**
+ * The selected Tenant's API while it runs: commands that read or change the Tenant's data never
+ * start it. Exit 3 when it is not running, 7 when it is not open.
+ */
+export async function runningTenantApi(deps, options = {}) {
+    const { ctx, admin } = await runningSelected(deps, options);
+    if (ctx.projectDir && ctx.link?.format === 3 && ctx.link.tenant === ctx.name) {
+        const project = await readCredentialsFile(credentialsPath(ctx.projectDir));
+        if (project && (await keyAuthenticates(deps.fetch, admin.runtimeUrl, project.applicationKey)))
+            return { name: ctx.name, runtimeUrl: admin.runtimeUrl, applicationKey: project.applicationKey };
+    }
+    const key = await hostKey({
+        admin,
+        runtimeUrl: admin.runtimeUrl,
+        id: CLI_KEY_ID,
+        file: ctx.paths.cliCredentials,
+        lock: ctx.paths.keysLock,
+    });
+    return { name: ctx.name, runtimeUrl: admin.runtimeUrl, applicationKey: key.applicationKey };
+}
 /**
  * Start the selected Tenant unless it is already running (`nylorun studio`): the
  * `start` code path without its output, its Tenant wait or the Project link. Compose
@@ -915,6 +1052,40 @@ async function ensureSelected(ctx, options) {
 export async function ensureStack(deps, options) {
     return await ensureSelected(await selectStack(deps, options.name === undefined ? {} : { name: options.name }), options);
 }
+/** The Tenant `nylorun sandbox` acts on; it must have been started once. */
+export async function selectTenant(deps, options = {}) {
+    await tidyMachine(deps);
+    const ctx = await selectStack(deps, options);
+    requireStackFiles(ctx);
+    return {
+        name: ctx.name,
+        paths: ctx.paths,
+        project: ctx.project,
+        compose: (...args) => composeArgs(ctx, ...args),
+    };
+}
+/**
+ * Rewrite the Tenant's Compose files with `sandboxes` set (an object) or removed (null),
+ * and bring it up again: Compose recreates the containers whose settings changed.
+ */
+export async function restartTenant(deps, options) {
+    const ctx = await selectStack(deps, options.name === undefined ? {} : { name: options.name });
+    await dockerPreflight(deps.docker);
+    await bringUp(ctx, { studio: false, sandboxes: options.sandboxes });
+}
+/** Ports every Tenant on this machine keeps for sandboxes, but the one under `except`. */
+export async function reservedSandboxPorts(deps, except) {
+    const reserved = await tenantPorts(nylorunRoot(deps), except);
+    for (const tenant of await listTenants(nylorunRoot(deps))) {
+        if (resolve(tenant.root) === except)
+            continue;
+        const sandboxes = (await readStackEnv(stackPaths(tenant.root)))?.sandboxes;
+        for (const port of [sandboxes?.harnessPort, sandboxes?.gatesPort, sandboxes?.egressPort])
+            if (port !== undefined)
+                reserved.add(port);
+    }
+    return reserved;
+}
 /** Add Studio's `next` path (e.g. `/tenants/<id>`) to a login URL. */
 export function withNext(loginUrl, next) {
     if (!next)

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

@@ -5,16 +5,15 @@
  * network and ports. Container, network and volume names are global on the Docker engine, so
  * every one is `<project>-<role>` (`nylorun-shop-studio`, network `nylorun-shop`, volume
  * `nylorun-shop-postgres`), labelled `dev.nylorun.tenant: <name>`; they are written here, from
- * the project and the Tenant's name. Everything else that varies (ports, the Postgres password,
- * UID/GID, the Host root, the images) comes from `docker/.env`.
+ * the project and the Tenant's name. Everything else that varies (ports, the Postgres password and the other
+ * secrets, UID/GID, the Host root, the images) comes from `docker/.env`.
  *
  * The Tenant's state is its Postgres database, executed through Restate, with its
  * history in s2-lite; the Runtime's /ready checks all three. Postgres initialises the
  * database with C collation (`--locale=C`) and runs with `wal_level=logical`: the stream
  * relay feeds s2-lite from the record over logical replication (Durable Streams), and
  * `max_slot_wal_keep_size` caps the WAL a stuck relay can hold. The Runtime creates the
- * Tenant on its first start, with its name (`NYLORUN_TENANT_NAME`) and the derived
- * principals of `NYLORUN_DERIVED_PRINCIPALS` (`project` for the Project link).
+ * Tenant on its first start, with its name (`NYLORUN_TENANT_NAME`).
  *
  * Restate signs requests to the Worker endpoint with the private key in
  * `docker/restate-identity.pem`, mounted read-only; the Runtime gets the public
@@ -25,8 +24,8 @@
  * which alone reads model credentials, and the Tool Gate (F4.1), which alone
  * holds remote MCP connections and their credentials and POSTs every Action
  * delivery. Every model call, remote MCP call and delivery of the loop crosses it
- * (NYLORUN_GATES_URL, with NYLORUN_GATES_TOKEN from `.env`); stdio MCP servers
- * still run in the runtime container. The gateway also runs keys (F4.2): the only
+ * (NYLORUN_GATES_URL, with NYLORUN_GATES_TOKEN from `.env`, or a run's token from the
+ * harness); MCP stdio servers run in the harness container. The gateway also runs keys (F4.2): the only
  * holder of the vault key, it runs every vault write that touches a secret and signs
  * every token (NYLORUN_KEYS_URL). The gateway mounts only the Host's Tenant directory
  * (`tenant/`) and its keys directory (`keys/`, the vault key), read-only: never
@@ -35,5 +34,46 @@
  * Restate's private key and `.env`. The runtime does not wait for the gateway: while
  * it is down, model and MCP calls fail, deliveries are retried, vault writes and
  * token minting answer 503, and the session takes the next message.
+ *
+ * The Object store (blueprint D35) is RustFS, single node and single drive, pinned by digest,
+ * on the `rustfs` volume; it is not published. Its credential is the access key `nylorun` and
+ * the secret key NYLORUN_OBJECT_STORE_SECRET_KEY from `.env`, and only the runtime and the
+ * gateway receive it (NYLORUN_OBJECT_STORE_*). The runtime creates the bucket at boot and
+ * reaches the store through its `s3` BlobStore.
+ *
+ * With `sandboxes` (after `nylorun sandbox enable`, F7.2) the `sandboxes` service runs the
+ * agent-sandbox driver: the only container holding the cluster credentials
+ * (`<Host root>/sandboxes`, read-only), not published, reached by the runtime alone with
+ * NYLORUN_SANDBOXES_TOKEN. The runtime gets an empty read-only mount over that directory.
+ * Sandbox pods reach the stack only on the Docker host's address (NYLORUN_SANDBOX_HOST_ADDRESS),
+ * where three ports are published on NYLORUN_SANDBOX_BIND: the runtime's Harness API listener
+ * (NYLORUN_SANDBOX_HARNESS_PORT → 4200: pods join and connect with host tokens), the
+ * gateway's gates (NYLORUN_SANDBOX_GATES_PORT → 4100: model and MCP calls with run tokens) and
+ * egress-gate (NYLORUN_SANDBOX_EGRESS_PORT → 4200 in the gateway, `--service gates,keys,egress`:
+ * CONNECT with the egress token, to the hosts the sandbox spec allows). The two HTTP listeners
+ * accept that address as a Host.
+ *
+ * The harness (F6.2, `harness: "remote"`, the default) runs every agent turn, MCP stdio server
+ * and workspace in its own container: the runtime image with `--service harness`, connected to
+ * core's Harness API (`ws://runtime:4200/nylorun/harness/v1`) with NYLORUN_HARNESS_TOKEN, its
+ * only credential, and calling models and remote MCP servers through the gateway with each
+ * run's token. It mounts only the Tenant's `sandboxes/`, `plugin-data/`, `home/` and `tmp/`
+ * under `/harness`, and the Host root's `plugins/` read-only at its own path (plugin roots name
+ * paths on this machine; the runtime mounts it there too). NYLORUN_HARNESS=in-process in `.env`
+ * rolls back to turns in the runtime container, without the harness service.
+ *
+ * Three networks: `store` (internal: no egress) joins Postgres, s2-lite, Restate and RustFS to
+ * the runtime and the gateway; `harness` joins the harness to the runtime and the gateway only;
+ * `default` carries egress and the published ports (runtime, gateway, Studio, sandboxes).
+ * Restate's admin port (its UI, unauthenticated) is published, and Restate joins `default`,
+ * only with `restateUi` (`nylorun start --restate-ui`).
+ *
+ * With `identity` (when `<Host root>/identity.yaml` exists) the runtime reads its trusted issuers
+ * from it, through the Host root mount (NYLORUN_IDENTITY_FILE=/nylorun/identity.yaml).
  */
-export declare function renderComposeFile(project: string, name: string): string;
+export declare function renderComposeFile(project: string, name: string, options?: {
+    sandboxes?: true;
+    harness?: "remote" | "in-process";
+    restateUi?: true;
+    identity?: true;
+}): string;