nylorun 0.6.0-beta → 0.8.0-beta

package/dist/stack/commands.js

@@ -13,17 +13,30 @@ import { readAdminKey, readHostConfig, STACK_CLIENT_HOST } from "./host-files.js
 import { runtimeImageOverridden, stackImages } from "./images.js";
 import { stackPaths } from "./paths.js";
 import { prepareStack, readStackEnv } from "./prepare.js";
-import { disconnectProxy, ensureProxySettings, PROXY_PROJECT, proxyDisabled, proxyOrigin, readProxySettings, readProxyStatus, refreshProxyRoutes, startProxy, stopProxy, } from "./proxy.js";
-import { assertTenantName, chooseTenantName, DEFAULT_TENANT, defaultNylorunRoot, listTenants, moveStackRoots, readTenantRecord, sanitizeTenantName, tenantRoot, tenantsDir, writeTenantRecord, } from "./stacks.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]
+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
-  down|stop [--tenant <name> | --all] stop the Tenant's containers (--all: every Tenant's, and the Studio proxy); keep volumes
+                                      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>]
                                       container logs (${STACK_SERVICES.join(", ")})
@@ -43,26 +56,11 @@ export function stackProject(env, name) {
 function nylorunRoot(deps) {
     return deps.nylorunRoot ?? defaultNylorunRoot();
 }
-/**
- * The Studio proxy serves the machine's Tenants (`~/.nylorun/tenants`), unless
- * NYLORUN_PROXY_DISABLED=1; a Host root or Compose project of its own (NYLORUN_HOME,
- * NYLORUN_COMPOSE_PROJECT, as the repository's smokes use) is outside it.
- */
-function proxied(ctx) {
-    const { env } = ctx.deps;
-    return !proxyDisabled(env) && !env.NYLORUN_HOME?.trim() && !env.NYLORUN_COMPOSE_PROJECT?.trim();
-}
-/** Studio's URL for browsers: through the proxy when it serves the Tenant, else its own port. */
-async function studioUrl(ctx, studioPort) {
-    const settings = proxied(ctx) ? await readProxySettings(nylorunRoot(ctx.deps)) : undefined;
-    return settings ? proxyOrigin(ctx.name, settings.port) : studioOrigin(studioPort);
-}
-/** The proxy's routes: every Tenant on this machine. */
-async function proxyRoutes(deps) {
-    return (await listTenants(nylorunRoot(deps))).map((tenant) => ({
-        name: tenant.name,
-        project: stackProject(deps.env, tenant.name),
-    }));
+/** Before every Tenant command: move 0.4's Host roots, remove 0.6's Studio proxy. */
+async function tidyMachine(deps) {
+    const base = nylorunRoot(deps);
+    await moveStackRoots(base, deps.err);
+    await removeOldProxy(deps.docker, base, deps.err);
 }
 /**
  * Compose's names for a 0.5 Tenant's volumes (`<project>_postgres`, …) that exist on this
@@ -78,13 +76,9 @@ async function oldVolumes(docker, project) {
         current: names.has(`${project}-postgres`),
     };
 }
-/**
- * Before `docker compose down` (`reset`, `delete`): detach the proxy from the Tenant's network
- * so Compose can remove it. After it: drop a 0.5 Tenant's volumes and network.
- */
+/** `docker compose down` (`reset`, `delete`), then drop a 0.5 Tenant's volumes and network. */
 async function composeDown(ctx, args) {
     const { docker } = ctx.deps;
-    await disconnectProxy(docker, ctx.project);
     const code = await docker.stream(args);
     if (code !== 0)
         throw new CliError(`docker compose down failed (exit ${code}).`, 1);
@@ -227,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 {
@@ -243,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;
@@ -356,14 +362,9 @@ async function tenantPorts(base, except) {
     }
     return reserved;
 }
-/** Ports other Tenants and the proxy keep, so a new Tenant avoids them. */
+/** Ports other Tenants keep, so a new Tenant avoids them. */
 async function reservedPorts(ctx) {
-    const base = nylorunRoot(ctx.deps);
-    const reserved = await tenantPorts(base, ctx.paths.root);
-    const proxy = await readProxySettings(base);
-    if (proxy)
-        reserved.add(proxy.port);
-    return reserved;
+    return await tenantPorts(nylorunRoot(ctx.deps), ctx.paths.root);
 }
 async function bringUp(ctx, options) {
     const { deps } = ctx;
@@ -377,10 +378,6 @@ async function bringUp(ctx, options) {
     const base = nylorunRoot(deps);
     const telemetry = await readTelemetry(base);
     const analytics = telemetryDecision(deps.env, telemetry).enabled;
-    // The proxy's port avoids every Tenant's; a new Tenant's ports then avoid the proxy's.
-    const proxy = proxied(ctx)
-        ? await ensureProxySettings(base, deps.ports, await tenantPorts(base))
-        : undefined;
     const prepared = await prepareStack({
         paths: ctx.paths,
         name: ctx.name,
@@ -400,7 +397,8 @@ async function bringUp(ctx, options) {
             : {}),
         ...(options.studioEmbedOrigins ? { studioEmbedOrigins: options.studioEmbedOrigins } : {}),
         ...(analytics ? { studioAnalyticsId: STUDIO_ANALYTICS_ID } : {}),
-        ...(proxy ? { studioPublicOrigin: proxyOrigin(ctx.name, proxy.port) } : {}),
+        ...(options.sandboxes !== undefined ? { sandboxes: options.sandboxes } : {}),
+        ...(options.restateUi !== undefined ? { restateUi: options.restateUi } : {}),
     });
     if (analytics && options.studio && telemetry.noticeShown === undefined) {
         deps.err(TELEMETRY_NOTICE);
@@ -414,15 +412,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"));
@@ -430,45 +437,24 @@ async function bringUp(ctx, options) {
         if (!studioStarted)
             deps.err(`Warning: Studio did not start (image ${prepared.env.studioImage}). The Runtime is up; see "nylorun logs studio".`);
     }
-    let studioUrl = studioOrigin(prepared.env.studioPort);
-    if (studioStarted && proxy) {
-        const up = await startProxy({
-            docker: deps.docker,
-            base,
-            settings: proxy,
-            routes: await proxyRoutes(deps),
-            err: deps.err,
-            ...(deps.pollMs !== undefined ? { pollMs: deps.pollMs } : {}),
-        });
-        if (up)
-            studioUrl = proxyOrigin(ctx.name, proxy.port);
-    }
     return {
         runtimeUrl,
         adminUrl,
         hostId: prepared.host.hostId,
         studioPort: prepared.env.studioPort,
-        studioUrl,
+        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));
-/**
- * A login URL on Studio's URL: through the proxy when it serves the Tenant (once; a proxy that
- * does not answer falls back, saying so), else on Studio's own port, retried while it starts.
- */
-async function tryStudioLogin(ctx, studio, adminKey) {
+/** A login URL on Studio's own port, retried while it starts. */
+async function tryStudioLogin(ctx, studioPort, adminKey) {
     const { deps } = ctx;
-    const origin = studioOrigin(studio.port);
-    if (studio.url !== origin) {
-        try {
-            return await mintStudioLogin({ fetch: deps.fetch, origin: studio.url, adminKey });
-        }
-        catch (error) {
-            deps.err(`Studio did not answer through the proxy at ${studio.url} (${errorText(error)}); signing in at ${origin} instead.`);
-        }
-    }
+    const origin = studioOrigin(studioPort);
     const deadline = Date.now() + (deps.loginTimeoutMs ?? 15_000);
     let lastError = "";
     for (;;) {
@@ -546,7 +532,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: [
@@ -555,6 +541,7 @@ async function start(deps, args) {
             "--no-link",
             "--allow-downgrade",
             "--studio-embed-origin-reset",
+            "--restate-ui",
         ],
         values: ["--tenant"],
         lists: ["--studio-embed-origin"],
@@ -572,6 +559,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 } }
             : {}),
@@ -581,10 +569,12 @@ 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)) {
-            const login = await tryStudioLogin(ctx, { port: started.studioPort, url: started.studioUrl }, started.adminKey);
+            const login = await tryStudioLogin(ctx, started.studioPort, started.adminKey);
             if (login)
                 await openLogin(ctx, withNext(login, tenantStudioPath(tenant.id)));
         }
@@ -631,7 +621,7 @@ async function stop(deps, args) {
     deps.out(`Stopped Tenant ${ctx.name}; its data is kept.`);
     return 0;
 }
-/** `stop --all`: every running Tenant on this machine, then the Studio proxy; volumes are kept. */
+/** `stop --all`: every running Tenant on this machine; volumes are kept. */
 async function stopAll(deps) {
     await dockerPreflight(deps.docker);
     const projects = (await composeProjects(deps.docker)) ?? new Map();
@@ -648,17 +638,11 @@ async function stopAll(deps) {
             throw new CliError(`docker compose stop failed for Tenant ${tenant.name} (exit ${code}).`, 1);
         stopped.push(tenant.name);
     }
-    const proxy = projects.get(PROXY_PROJECT) === "running" && (await stopProxy(deps.docker));
     deps.out(stopped.length
-        ? `Stopped Tenants ${stopped.join(", ")}${proxy ? " and the Studio proxy" : ""}; their data is kept.`
-        : `No Tenant was running${proxy ? "; stopped the Studio proxy" : ""}.`);
+        ? `Stopped Tenants ${stopped.join(", ")}; their data is kept.`
+        : "No Tenant was running.");
     return 0;
 }
-async function studioUrls(ctx, port) {
-    const url = await studioUrl(ctx, port);
-    const direct = studioOrigin(port);
-    return url === direct ? { url } : { url: direct, proxyUrl: url };
-}
 async function stackStatus(ctx) {
     const base = {
         name: ctx.name,
@@ -667,8 +651,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))
@@ -686,11 +671,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",
@@ -703,29 +691,31 @@ async function stackStatus(ctx) {
         },
         ...(tenant ? { tenant } : {}),
         studio: {
-            ...(persisted.studioPort ? await studioUrls(ctx, persisted.studioPort) : {}),
+            ...(persisted.studioPort ? { url: studioOrigin(persisted.studioPort) } : {}),
             state: studio ? [studio.state, studio.health].filter(Boolean).join(", ") : "absent",
             ...(persisted.studioFrameAncestors
                 ? { embedOrigins: persisted.studioFrameAncestors }
                 : {}),
         },
-        restate: persisted.restatePort
-            ? { url: `http://${STACK_CLIENT_HOST}:${persisted.restatePort}` }
-            : {},
+        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,
     };
 }
-/** The Studio proxy, as data (`nylorun doctor`). */
-export async function readProxyReport(deps) {
-    return await readProxyStatus(deps.docker, nylorunRoot(deps), deps.env);
-}
 /** What `nylorun status` reports, as data (`nylorun doctor`). */
 export async function readStackStatus(deps, options = {}) {
-    await moveStackRoots(nylorunRoot(deps), deps.err);
+    await tidyMachine(deps);
     return await stackStatus(await selectStack(deps, options));
 }
 function describeTenant(tenant) {
@@ -760,13 +750,19 @@ async function status(deps, args) {
         out(`Runtime     ${result.runtime.url ?? "?"}  ${runtimeDetail}`);
         if (result.runtime.adminUrl)
             out(`Admin API   ${result.runtime.adminUrl}  (operators only, never proxied)`);
-        const also = result.studio.proxyUrl ? `also ${result.studio.url}; ` : "";
-        out(`Studio      ${result.studio.proxyUrl ?? result.studio.url ?? "?"}  ${result.studio.state} (${also}log in with "nylorun studio")`);
+        out(`Studio      ${result.studio.url ?? "?"}  ${result.studio.state} (log in with "nylorun studio")`);
         if (result.studio.embedOrigins?.length)
             out(`Embeds      ${result.studio.embedOrigins.join(" ")}  (may show Studio in a frame)`);
         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
@@ -783,7 +779,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))
@@ -848,7 +844,6 @@ async function ls(deps, args) {
     const memory = [...(projects?.values() ?? [])].includes("running")
         ? await tenantMemory(deps.docker)
         : undefined;
-    const proxy = proxyDisabled(deps.env) ? undefined : await readProxySettings(base);
     const tenants = [];
     for (const entry of await listTenants(base)) {
         const persisted = (await readStackEnv(stackPaths(entry.root))) ?? {};
@@ -862,13 +857,7 @@ async function ls(deps, args) {
             ...(persisted.runtimePort
                 ? { runtimeUrl: `http://${STACK_CLIENT_HOST}:${persisted.runtimePort}` }
                 : {}),
-            ...(persisted.studioPort
-                ? {
-                    studioUrl: proxy
-                        ? proxyOrigin(entry.name, proxy.port)
-                        : studioOrigin(persisted.studioPort),
-                }
-                : {}),
+            ...(persisted.studioPort ? { studioUrl: studioOrigin(persisted.studioPort) } : {}),
             ports: {
                 ...(persisted.runtimePort ? { runtime: persisted.runtimePort } : {}),
                 ...(persisted.adminPort ? { admin: persisted.adminPort } : {}),
@@ -920,7 +909,6 @@ async function deleteStack(deps, args) {
         ? composeArgs(ctx, "down", "--volumes", "--remove-orphans")
         : ["compose", "--project-name", ctx.project, "down", "--volumes", "--remove-orphans"]);
     await rm(ctx.paths.root, { recursive: true, force: true });
-    await refreshProxyRoutes(deps.docker, base, await proxyRoutes(deps));
     deps.out(`Deleted Tenant ${name}: its containers, volumes and Host root (vault key included).`);
     return 0;
 }
@@ -938,6 +926,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;
@@ -955,7 +946,7 @@ async function runningStack(ctx, options) {
         hostId: host.hostId,
         adminKey,
         studioPort: persisted.studioPort,
-        studioUrl: await studioUrl(ctx, persisted.studioPort),
+        studioUrl: studioOrigin(persisted.studioPort),
         studioUp,
         started: false,
     };
@@ -980,6 +971,26 @@ async function ensureSelected(ctx, options) {
         started: !runtimeWasUp,
     };
 }
+/**
+ * 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 = 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 {
+        name: ctx.name,
+        runtimeUrl: running.runtimeUrl,
+        applicationKey: deriveTenantKey(running.adminKey, tenant.id, PROJECT_PRINCIPAL_ID),
+    };
+}
 /**
  * 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
@@ -988,6 +999,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)
@@ -1005,7 +1050,7 @@ export function tenantStudioPath(tenantId) {
  * Undefined (after a warning) when Studio does not answer.
  */
 export async function studioLoginUrl(deps, running, next) {
-    const login = await tryStudioLogin({ deps }, { port: running.studioPort, url: running.studioUrl }, running.adminKey);
+    const login = await tryStudioLogin({ deps }, running.studioPort, running.adminKey);
     return login === undefined ? undefined : withNext(login, next);
 }
 async function studio(deps, args, options = {}) {
@@ -1035,7 +1080,6 @@ async function studio(deps, args, options = {}) {
         deps.out(`Studio    ${login}`);
         return 0;
     }
-    // The login's origin: the proxy's, or Studio's own port when the proxy did not answer.
     const origin = new URL(login).origin;
     deps.out(`Studio    ${next ? new URL(next, origin).toString() : origin}`);
     await openLogin({ deps }, login);
@@ -1043,7 +1087,7 @@ async function studio(deps, args, options = {}) {
 }
 /** `nylorun studio`, landing on `next` when given, else on the Tenant's page. */
 export async function runStudioCommand(args, deps, options = {}) {
-    await moveStackRoots(nylorunRoot(deps), deps.err);
+    await tidyMachine(deps);
     return await studio(deps, args, options);
 }
 const COMMANDS = {
@@ -1067,6 +1111,6 @@ export async function runStackCommand(name, args, deps) {
     const command = COMMANDS[name];
     if (!command)
         throw usageError(`Unknown command ${name}.\n${stackUsage}`);
-    await moveStackRoots(nylorunRoot(deps), deps.err);
+    await tidyMachine(deps);
     return await command(deps, args);
 }

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

@@ -5,8 +5,8 @@
  * 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, Studio's public origins) 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
@@ -25,8 +25,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 +35,42 @@
  * 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`).
  */
-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;
+}): string;