nylorun 0.7.0-beta → 0.8.0-beta

package/dist/sandbox/probe.js

@@ -0,0 +1,137 @@
+import { randomBytes } from "node:crypto";
+import { CliError } from "../errors.js";
+import { networkPolicy, PROBE_IMAGE, probePod } from "./manifests.js";
+const DOCKER_DESKTOP_HOST = "192.168.65.254";
+/** Docker Desktop and OrbStack forward the host address to this machine's loopback. */
+export function defaultBind(context, hostAddress) {
+    if (hostAddress === DOCKER_DESKTOP_HOST || context === "docker-desktop" || context === "orbstack")
+        return "127.0.0.1";
+    return hostAddress;
+}
+const IPV4 = /^(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)$/;
+export function assertIPv4(value, option) {
+    if (!IPV4.test(value))
+        throw new CliError(`${option} must be an IPv4 address: ${value}`, 2);
+    return value;
+}
+/** The last IPv4 address `nslookup` prints for the name (the first is the DNS server). */
+export function parseNslookup(output) {
+    const answer = output.split(/Name:\s*\S+/).slice(1).join("\n");
+    const addresses = [...answer.matchAll(/Address(?:es)?:?\s*(?:\d+\s+)?([0-9.]+)\b/g)]
+        .map((match) => match[1])
+        .filter((address) => IPV4.test(address));
+    return addresses.at(-1);
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** `wget` from a probe pod; true when the connection succeeds. */
+async function reaches(kube, namespace, pod, address, port) {
+    const result = await kube.run(["exec", "-n", namespace, pod, "--", "wget", "-q", "-O", "-", "-T", "3", `http://${address}:${port}/`], { timeoutMs: 20_000 });
+    return result.code === 0;
+}
+export async function runProbe(deps, options) {
+    const { kube, docker } = deps;
+    const suffix = randomBytes(3).toString("hex");
+    const namespace = `nylorun-sbx-probe-${suffix}`;
+    const listener = namespace;
+    const poll = deps.pollMs ?? 1000;
+    let listenerStarted = false;
+    const fail = (message) => new CliError(`Refusing context ${kube.context}: ${message}`, 6);
+    try {
+        await kube.apply("Creating the probe namespace", [
+            { apiVersion: "v1", kind: "Namespace", metadata: { name: namespace, labels: { "app.kubernetes.io/managed-by": "nylorun" } } },
+            probePod(namespace, "peer", { role: "peer", serve: true }),
+            probePod(namespace, "control", { role: "control" }),
+            probePod(namespace, "restricted", { role: "restricted" }),
+        ]);
+        await kube.check("Waiting for the probe pods", [
+            "wait", "--for=condition=Ready", "pod", "--all", "-n", namespace, "--timeout=180s",
+        ], { timeoutMs: 200_000 });
+        let hostAddress = options.hostAddress;
+        if (!hostAddress) {
+            const lookup = await kube.run(["exec", "-n", namespace, "control", "--", "nslookup", "host.docker.internal"]);
+            // busybox nslookup may exit non-zero after an NXDOMAIN on a search domain: parse anyway.
+            hostAddress = parseNslookup(lookup.stdout);
+            if (!hostAddress)
+                throw fail("pods cannot resolve host.docker.internal. Pass --host-address with the Docker host's address as pods reach it (172.17.0.1 for kind on Linux).");
+        }
+        const bindAddress = options.bindAddress ?? defaultBind(kube.context, hostAddress);
+        const allowed = await deps.ports.pickFree();
+        let denied = await deps.ports.pickFree();
+        if (denied === allowed)
+            denied = await deps.ports.pickFree();
+        const started = await docker.run([
+            "run", "--detach", "--rm", "--name", listener, "--label", "dev.nylorun.probe=true",
+            "--publish", `${bindAddress}:${allowed}:8080`, "--publish", `${bindAddress}:${denied}:8081`,
+            PROBE_IMAGE, "sh", "-c",
+            "echo ok > /tmp/index.html; httpd -p 8081 -h /tmp; exec httpd -f -p 8080 -h /tmp",
+        ]);
+        if (started.code !== 0)
+            throw fail(`could not publish a probe listener on ${bindAddress}: ${started.stderr.trim()}`);
+        listenerStarted = true;
+        const peer = (await kube.check("Reading the peer pod's address", [
+            "get", "pod", "peer", "-n", namespace, "-o", "jsonpath={.status.podIP}",
+        ])).trim();
+        if (!(await reaches(kube, namespace, "control", peer, 8080)))
+            throw fail("a pod cannot reach another pod in its namespace (the probe cannot tell a policy from a broken network).");
+        if (!(await reaches(kube, namespace, "control", hostAddress, allowed)))
+            throw fail(`pods cannot reach ${hostAddress}:${allowed} on the Docker host (published on ${bindAddress}). Pass --host-address and --bind-address for this cluster.`);
+        await kube.apply("Applying the probe NetworkPolicy", [
+            networkPolicy(namespace, hostAddress, [allowed], { name: "probe", podSelector: { "nylorun.dev/probe": "restricted" } }),
+        ]);
+        const deadline = Date.now() + (deps.policyTimeoutMs ?? 30_000);
+        while (await reaches(kube, namespace, "restricted", peer, 8080)) {
+            if (Date.now() > deadline)
+                throw fail("NetworkPolicy is not enforced: a pod under a deny policy still reached another pod. Sandboxes need a CNI that enforces NetworkPolicy (kindnet with policy support, Calico, Cilium).");
+            await sleep(poll);
+        }
+        if (await reaches(kube, namespace, "restricted", hostAddress, denied))
+            throw fail(`NetworkPolicy is not enforced per port: a restricted pod reached ${hostAddress}:${denied}.`);
+        if (!(await reaches(kube, namespace, "restricted", hostAddress, allowed)))
+            throw fail(`a restricted pod cannot reach the allowed ${hostAddress}:${allowed}: the policy's ipBlock does not match the host route.`);
+        const notPulled = options.prePull?.length ? await prePull(deps, namespace, options.prePull) : [];
+        return { hostAddress, bindAddress, enforced: true, probedAt: new Date().toISOString(), notPulled };
+    }
+    finally {
+        if (listenerStarted)
+            await docker.run(["rm", "--force", listener]);
+        await kube.run(["delete", "namespace", namespace, "--ignore-not-found", "--wait=false"]);
+    }
+}
+/**
+ * Pull images on every node with a pod per node and image (a cold pull of a pack-sized image
+ * takes about 30 s). Best effort: images that do not pull (a local build, no registry) are
+ * returned, for a warning.
+ */
+async function prePull(deps, namespace, images) {
+    const { kube } = deps;
+    const nodes = JSON.parse(await kube.check("Listing nodes", ["get", "nodes", "-o", "json"]));
+    const pods = nodes.items.flatMap((node, n) => images.map((image, i) => ({
+        name: `pull-${n}-${i}`,
+        image,
+        manifest: probePod(namespace, `pull-${n}-${i}`, {
+            role: "pull", image, nodeName: node.metadata.name, command: ["true"],
+        }),
+    })));
+    await kube.apply("Pre-pulling images", pods.map((pod) => pod.manifest));
+    const failed = new Set();
+    const done = new Set();
+    const deadline = Date.now() + 300_000;
+    while (done.size + failed.size < pods.length && Date.now() < deadline) {
+        const list = await kube.getJson(["pods", "-n", namespace, "-l", "nylorun.dev/probe=pull"]);
+        for (const item of list?.items ?? []) {
+            const pod = pods.find((p) => p.name === item.metadata.name);
+            if (!pod || done.has(pod.name) || failed.has(pod.name))
+                continue;
+            const reason = item.status?.containerStatuses?.[0]?.state?.waiting?.reason ?? "";
+            if (/ErrImagePull|ImagePullBackOff|InvalidImageName|ErrImageNeverPull/.test(reason))
+                failed.add(pod.name);
+            else if (item.status?.phase && item.status.phase !== "Pending")
+                done.add(pod.name);
+        }
+        if (done.size + failed.size < pods.length)
+            await sleep(deps.pollMs ?? 2000);
+    }
+    return images.filter((image) => pods.some((pod) => pod.image === image && !done.has(pod.name)));
+}

package/dist/stack/commands.d.ts

@@ -1,8 +1,10 @@
 import type { HostTenant } from "@nylorun/core/contracts";
 import { type ComposeService, type DockerRunner } from "./docker.js";
+import type { HarnessMode, SandboxStackEnv } from "./env-file.js";
+import { type StackPaths } from "./paths.js";
 import type { PortProbe } from "./ports.js";
 import { type FetchLike } from "./studio-login.js";
-export declare const STACK_SERVICES: readonly ["postgres", "restate", "s2-lite", "gateway", "runtime", "studio"];
+export declare const STACK_SERVICES: readonly ["postgres", "restate", "s2-lite", "rustfs", "gateway", "runtime", "harness", "studio"];
 export declare const stackUsage: string;
 export interface StackDeps {
     /** Environment snapshot (NYLORUN_HOME, NYLORUN_TENANT, image overrides, NYLORUN_COMPOSE_PROJECT). */
@@ -79,14 +81,27 @@ export interface StackStatus {
         /** Exact origins that may show Studio in a frame (Studio §8.9). */
         embedOrigins?: string[];
     };
+    /** Restate's UI: `url` only while published (`nylorun start --restate-ui`). */
     restate: {
         url?: string;
+        published: boolean;
     };
     /** The gateway container (the Model Gate), in the combined packing. */
     gateway: {
         state: string;
         healthy: boolean;
     };
+    /**
+     * Where agent turns, MCP servers and workspaces run (F6.2): `remote`, the harness container,
+     * or `in-process`, the runtime container (`NYLORUN_HARNESS` in .env). `connected` counts the
+     * harnesses attached to the Tenant, as the Runtime reports them.
+     */
+    harness: {
+        mode: HarnessMode;
+        state: string;
+        healthy: boolean;
+        connected?: number;
+    };
     services: ComposeService[];
 }
 /** What `nylorun status` reports, as data (`nylorun doctor`). */
@@ -113,6 +128,21 @@ export interface StackEndpoints {
     /** This call started the Runtime (it was not running before). */
     started: boolean;
 }
+/** The running Tenant's API, reached as the Project's derived principal (`nylorun sandbox`). */
+export interface TenantApi {
+    /** The Tenant's name. */
+    name: string;
+    runtimeUrl: string;
+    /** The `project` derived principal's key, derived from the admin key; never stored. */
+    applicationKey: string;
+}
+/**
+ * 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 declare function runningTenantApi(deps: StackDeps, options?: {
+    name?: string;
+}): Promise<TenantApi>;
 /**
  * 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
@@ -122,6 +152,28 @@ export declare function ensureStack(deps: StackDeps, options: {
     studio: boolean;
     name?: string;
 }): Promise<StackEndpoints>;
+/** A started Tenant as `nylorun sandbox` sees it. */
+export interface SelectedTenant {
+    name: string;
+    paths: StackPaths;
+    project: string;
+    /** `docker compose` arguments for this Tenant's project and files. */
+    compose(...args: string[]): string[];
+}
+/** The Tenant `nylorun sandbox` acts on; it must have been started once. */
+export declare function selectTenant(deps: StackDeps, options?: {
+    name?: string;
+}): Promise<SelectedTenant>;
+/**
+ * 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 declare function restartTenant(deps: StackDeps, options: {
+    name?: string;
+    sandboxes: SandboxStackEnv | null;
+}): Promise<void>;
+/** Ports every Tenant on this machine keeps for sandboxes, but the one under `except`. */
+export declare function reservedSandboxPorts(deps: StackDeps, except: string): Promise<Set<number>>;
 /** Add Studio's `next` path (e.g. `/tenants/<id>`) to a login URL. */
 export declare function withNext(loginUrl: string, next: string | undefined): string;
 /** The Tenant's Studio page, as a login `next` path. */

package/dist/stack/commands.js

@@ -15,13 +15,27 @@ 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]
+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;
@@ -371,6 +397,8 @@ async function bringUp(ctx, options) {
             : {}),
         ...(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 +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"));
@@ -408,6 +445,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));
@@ -492,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: [
@@ -501,6 +541,7 @@ async function start(deps, args) {
             "--no-link",
             "--allow-downgrade",
             "--studio-embed-origin-reset",
+            "--restate-ui",
         ],
         values: ["--tenant"],
         lists: ["--studio-embed-origin"],
@@ -518,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 } }
             : {}),
@@ -527,6 +569,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 +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))
@@ -626,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",
@@ -649,13 +697,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 +754,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 +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))
@@ -865,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;
@@ -907,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
@@ -915,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)

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) 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;