nylorun 0.28.0-beta → 0.29.1-beta

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # nylorun
 
+## 0.29.1-beta
+
+### Patch Changes
+
+- Pin runtime to the tested release.
+
+## 0.29.0-beta
+
+### Minor Changes
+
+- f87ba81: Pods on Agent Substrate (preview, ADR-138 Phase 1a). `nylorun local sandbox enable --context <name> --backend substrate` runs the Tenant's sandboxes as Agent Substrate v1.0 actors instead of agent-sandbox Sandboxes, on a Kubernetes 1.37 cluster with Substrate installed (Docker Desktop's kind cluster, or Substrate's own kind script). It creates the Tenant's namespace and the sandboxes service's RBAC, makes the Tenant's atespace with the service as its editor, gives actors a name for the edge in CoreDNS, and publishes the edge's two ports from the `sandboxes` service: a TLS front, in that container, through which actors reach the Harness API and the gates. The default backend stays agent-sandbox, and nothing changes for a Tenant that does not pass `--backend substrate`.
+
+  The sandboxes service drives Substrate's API: a template per pod incarnation, pinned by digest; an egress policy from the Agent's network (its preset, hosts and suffixes, which the core now sends with each pod); suspend and resume for `mode`; and the same `/v1/pods` contract, so the core is unchanged. Not yet on Substrate: keys injected at egress, builds and tags; those come in Phase 1b.
+
+### Patch Changes
+
+- 0c6634b: `GET /v1/tenant/sandbox`'s `cluster` names its `backend` (`agent-sandbox` or `substrate`) and, on Agent Substrate, its `atespace`. `nylorun doctor sandbox` prints the Tenant's pods line (backend, context, namespace, ready), and Studio's Sandbox section says Agent Substrate with the atespace.
+- Pin core to the tested release.
+- Pin agents to the tested release.
+- Pin admin to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [0c6634b]
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/core@0.39.0-beta
+  - @nylorun/agents@0.36.2-beta
+  - @nylorun/admin@0.19.15-beta
+
 ## 0.28.0-beta
 
 ### Minor Changes

package/README.md

@@ -119,7 +119,7 @@ nylorun local ls [--json]          # the Tenants on this machine, with their sta
 nylorun local delete <tenant> --yes   # remove a Tenant: containers, volumes, Host root and vault key
 nylorun local logs [service] [--tenant <name>] [-f] [--tail <n>]   # postgres, restate, s2-lite, rustfs, gateway, runtime, harness, studio, sandboxes
 nylorun local reset [--tenant <name>] [--yes]   # delete the Tenant's volumes, Tenant directory and vault key; the next start creates it anew
-nylorun local sandbox enable --context <name> [--tenant <name>] [--host-address <ip>] [--bind-address <ip>] [--probe-ports <allowed>,<denied>] [--no-pull]
+nylorun local sandbox enable --context <name> [--tenant <name>] [--backend agent-sandbox|substrate] [--host-address <ip>] [--bind-address <ip>] [--probe-ports <allowed>,<denied>] [--no-pull]
 nylorun local sandbox disable [--tenant <name>] [--delete-namespace]
 nylorun local sandbox status [--tenant <name>] [--json]   # pods on a Kubernetes context (see Sandboxes)
 nylorun local telemetry [status|enable|disable]   # Studio's anonymous usage analytics
@@ -446,6 +446,32 @@ then run `enable` again.
 the namespace and every sandbox in it). Sessions run in a pod when their
 Agent's manifest has `runtime.kind` `pod`.
 
+### Pods on Agent Substrate (preview)
+
+`nylorun local sandbox enable --context <name> --backend substrate` runs the Tenant's pods as
+[Agent Substrate](https://github.com/agent-substrate/substrate) v1.0 actors instead
+([ADR-138](https://github.com/nylorun/factory/blob/main/decisions/engine/2026-11-09-substrate-replaces-agent-sandbox.md),
+Phase 1). Actors suspend to a snapshot of their memory and resume where they stopped, which suits
+sessions that are short and mostly asleep. The cluster needs Kubernetes 1.37 with Substrate v1.0
+installed (its `ate-system` namespace and `api` Service): a kind cluster on Docker Desktop, made
+with Substrate's own kind script, works. `enable` refuses a context without Substrate.
+
+It only touches the context you name. It creates the namespace `nylorun-sbx-<tenant>` and a
+ServiceAccount allowed only what the sandboxes service uses (its state ConfigMaps, a token for
+itself, a port-forward to Substrate's API and Substrate's trust bundles), and adds a `hosts` entry
+to CoreDNS so that actors resolve the Tenant's edge, `nylorun-sbx-<tenant>.edge.nylorun.internal`,
+to the Docker host. The edge is a TLS front in the `sandboxes` container, published on two host
+ports (8793 and 8794 by default), through which actors reach the Harness API and the gates; its
+certificate is made for that name and its CA is given to each actor. Then, as one of Substrate's
+owners (a 10-minute token for `ate-system/ate-client`, deleted after use), it makes the Tenant's
+atespace with the sandboxes service as its editor.
+
+Each Agent's network (preset, hosts, suffixes) becomes its actors' egress policy: only the edge
+and the allowed hosts resolve and connect. Keys injected at egress, builds and tags are not on
+Substrate yet. `nylorun local sandbox status` names the backend, the atespace and the edge.
+`disable` works as for agent-sandbox; the atespace stays until you delete it with Substrate's
+tools.
+
 ## Host root
 
 The **Host root** is `~/.nylorun/tenants/<name>/`, or `NYLORUN_HOME`. It is

package/dist/client/doctor.d.ts

@@ -20,6 +20,15 @@ export type SandboxReport = {
             environments?: number;
         };
     };
+    /** The Tenant's cluster for pod Agents (`nylorun local sandbox enable`), when it has one. */
+    cluster?: {
+        namespace: string;
+        context: string;
+        ready: boolean;
+        backend?: "agent-sandbox" | "substrate";
+        atespace?: string;
+        controllerVersion?: string;
+    } | null;
 };
 /**
  * `nylorun doctor sandbox`: the Tenant's sandbox report (`GET /v1/tenant/sandbox`, Management API)

package/dist/client/doctor.js

@@ -59,6 +59,18 @@ export async function doctorSandbox(deps, options) {
                 .filter((item) => item !== undefined)
                 .join(", ") || "-",
         ]);
+    const cluster = report.cluster;
+    if (cluster)
+        rows.push([
+            "pods",
+            [
+                cluster.backend === "substrate"
+                    ? `Agent Substrate (preview), atespace ${cluster.atespace ?? "?"}`
+                    : `agent-sandbox${cluster.controllerVersion ? ` ${cluster.controllerVersion}` : ""}`,
+                `on ${cluster.context}, namespace ${cluster.namespace}`,
+                cluster.ready ? "ready" : "not ready",
+            ].join(", "),
+        ]);
     rows.push([
         "selected",
         report.backend

package/dist/sandbox/cluster-file.d.ts

@@ -28,6 +28,23 @@ export interface ClusterFile {
         probedAt: string;
     };
     enabledAt: string;
+    /** agent-sandbox when absent; substrate for Agent Substrate (ADR-138, preview). */
+    backend?: "agent-sandbox" | "substrate";
+    /** Agent Substrate: where the Tenant's actors live and the edge actors reach the Runtime by. */
+    substrate?: {
+        atespace: string;
+        systemNamespace: string;
+        apiService: string;
+        serviceAccount: string;
+        endpoint?: string;
+        version?: string;
+        edge: {
+            host: string;
+            harnessPort: number;
+            gatesPort: number;
+        };
+        workerSelector?: Record<string, string>;
+    };
 }
 export declare function sandboxesDir(root: string): string;
 export declare function clusterFilePath(root: string): string;

package/dist/sandbox/commands.d.ts

@@ -3,7 +3,7 @@ import type { FetchLike } from "../stack/studio-login.js";
 import { type ClusterFile } from "./cluster-file.js";
 import { type Kube, type KubectlRunner } from "./kubectl.js";
 import { type ProbePorts } from "./probe.js";
-export declare const sandboxUsage = "  sandbox enable --context <name> [--tenant <name>] [--host-address <ip>] [--bind-address <ip>] [--probe-ports <allowed>,<denied>] [--no-pull]\n                                      run the Tenant's sandboxes as pods on that kubeconfig context (agent-sandbox v1.0.10)\n  sandbox disable [--tenant <name>] [--delete-namespace]\n                                      stop the sandboxes service and forget the cluster\n  sandbox status [--tenant <name>] [--json]\n                                      the cluster, the sandboxes service's readiness and what it reports";
+export declare const sandboxUsage = "  sandbox enable --context <name> [--tenant <name>] [--backend agent-sandbox|substrate] [--host-address <ip>] [--bind-address <ip>] [--probe-ports <allowed>,<denied>] [--no-pull]\n                                      run the Tenant's sandboxes as pods on that kubeconfig context (agent-sandbox v1.0.10),\n                                      or as Agent Substrate actors (--backend substrate, preview: Kubernetes 1.37 with Substrate v1.0 installed)\n  sandbox disable [--tenant <name>] [--delete-namespace]\n                                      stop the sandboxes service and forget the cluster\n  sandbox status [--tenant <name>] [--json]\n                                      the cluster, the sandboxes service's readiness and what it reports";
 /** The default workload image (D36), pre-pulled with the Runtime image. */
 export declare const DEFAULT_SANDBOX_IMAGE = "python:3.13-slim";
 export interface SandboxDeps {
@@ -21,6 +21,8 @@ export interface SandboxDeps {
  * (seen on GKE right after the apply).
  */
 export declare function waitForCrd(k: Kube, pollMs: number): Promise<void>;
+/** The ServiceAccount token the token controller writes into the Secret. */
+export declare function serviceAccountToken(k: Kube, namespace: string, pollMs: number): Promise<string>;
 export interface InstallResult {
     cluster: ClusterFile;
     /** The ServiceAccount token. */
@@ -45,5 +47,29 @@ export declare function installCluster(deps: SandboxDeps, input: {
         egress: number;
     };
 }): Promise<InstallResult>;
+/**
+ * `enable --backend substrate` against one context (ADR-138, preview): checks Substrate is
+ * installed, makes the Tenant's namespace and RBAC, finds the Docker host's address as pods see
+ * it, and names the edge for actors in CoreDNS. The atespace is made later, by the sandboxes
+ * image's substrate-setup, once cluster.json is written.
+ */
+export declare function installSubstrate(deps: SandboxDeps, input: {
+    context: string;
+    tenant: string;
+    hostAddress?: string;
+    bindAddress?: string;
+    ports: {
+        harness: number;
+        gates: number;
+        egress: number;
+    };
+    edgePorts: {
+        harness: number;
+        gates: number;
+    };
+}): Promise<{
+    cluster: ClusterFile;
+    token: string;
+}>;
 /** `nylorun local sandbox <enable|disable|status>`. */
 export declare function runSandboxCommand(args: readonly string[], deps: SandboxDeps): Promise<number>;

package/dist/sandbox/commands.js

@@ -9,15 +9,21 @@ import { readStackEnv } from "../stack/prepare.js";
 import { apiRoute, readClusterFile, removeClusterFiles, writeClusterFiles, } from "./cluster-file.js";
 import { contexts, kube } from "./kubectl.js";
 import { CONTROLLER_DEPLOYMENT, CONTROLLER_NAMESPACE, CONTROLLER_SHA256, CONTROLLER_URL, CONTROLLER_VERSION, networkPolicy, SANDBOX_API_VERSION, SANDBOX_CRD, tenantLabel, tenantManifests, tenantNamespace, TOKEN_SECRET, } from "./manifests.js";
-import { assertIPv4, parseProbePorts, runProbe } from "./probe.js";
+import { assertIPv4, defaultBind, parseNslookup, parseProbePorts, runProbe } from "./probe.js";
+import { corefileWithEdge, edgeHost, PREFERRED_EDGE_PORTS, SUBSTRATE_API_SERVICE, SUBSTRATE_AUDIENCE, SUBSTRATE_NAMESPACE, SUBSTRATE_OWNER_ACCOUNT, substrateManifests, } from "./substrate.js";
+import { PROBE_IMAGE, SERVICE_ACCOUNT } from "./manifests.js";
+import { join } from "node:path";
+import { rm, writeFile } from "node:fs/promises";
+import { sandboxesDir } from "./cluster-file.js";
 import { cliTuning } from "../tuning.js";
-export const sandboxUsage = `  sandbox enable --context <name> [--tenant <name>] [--host-address <ip>] [--bind-address <ip>] [--probe-ports <allowed>,<denied>] [--no-pull]
-                                      run the Tenant's sandboxes as pods on that kubeconfig context (agent-sandbox ${CONTROLLER_VERSION})
+export const sandboxUsage = `  sandbox enable --context <name> [--tenant <name>] [--backend agent-sandbox|substrate] [--host-address <ip>] [--bind-address <ip>] [--probe-ports <allowed>,<denied>] [--no-pull]
+                                      run the Tenant's sandboxes as pods on that kubeconfig context (agent-sandbox ${CONTROLLER_VERSION}),
+                                      or as Agent Substrate actors (--backend substrate, preview: Kubernetes 1.37 with Substrate v1.0 installed)
   sandbox disable [--tenant <name>] [--delete-namespace]
                                       stop the sandboxes service and forget the cluster
   sandbox status [--tenant <name>] [--json]
                                       the cluster, the sandboxes service's readiness and what it reports`;
-const ENABLE_USAGE = "nylorun local sandbox enable --context <name> [--tenant <name>] [--host-address <ip>] [--bind-address <ip>] [--probe-ports <allowed>,<denied>] [--no-pull]";
+const ENABLE_USAGE = "nylorun local sandbox enable --context <name> [--tenant <name>] [--backend agent-sandbox|substrate] [--host-address <ip>] [--bind-address <ip>] [--probe-ports <allowed>,<denied>] [--no-pull]";
 /** The default workload image (D36), pre-pulled with the Runtime image. */
 export const DEFAULT_SANDBOX_IMAGE = "python:3.13-slim";
 /** Preferred host ports for the Harness API, gates and egress (pods reach them). */
@@ -82,7 +88,7 @@ export async function waitForCrd(k, pollMs) {
     }
 }
 /** The ServiceAccount token the token controller writes into the Secret. */
-async function serviceAccountToken(k, namespace, pollMs) {
+export async function serviceAccountToken(k, namespace, pollMs) {
     const deadline = Date.now() + cliTuning().sandbox.tokenWaitMs;
     for (;;) {
         const secret = await k.getJson(["secret", TOKEN_SECRET, "-n", namespace]);
@@ -153,14 +159,122 @@ export async function installCluster(deps, input) {
         notPulled: probe.notPulled,
     };
 }
+/**
+ * `enable --backend substrate` against one context (ADR-138, preview): checks Substrate is
+ * installed, makes the Tenant's namespace and RBAC, finds the Docker host's address as pods see
+ * it, and names the edge for actors in CoreDNS. The atespace is made later, by the sandboxes
+ * image's substrate-setup, once cluster.json is written.
+ */
+export async function installSubstrate(deps, input) {
+    const k = kube(deps.kubectl, input.context);
+    const pollMs = deps.pollMs ?? cliTuning().sandbox.pollMs;
+    const { server, caData } = await readKubeconfig(k);
+    let route;
+    try {
+        route = apiRoute(server);
+    }
+    catch (error) {
+        throw new CliError(`Context ${input.context}: ${error instanceof Error ? error.message : String(error)}`, 6);
+    }
+    const service = await k.getJson([
+        "service", SUBSTRATE_API_SERVICE, "-n", SUBSTRATE_NAMESPACE,
+    ]);
+    if (!service)
+        throw new CliError(`Refusing context ${input.context}: Agent Substrate is not installed (no ${SUBSTRATE_NAMESPACE}/${SUBSTRATE_API_SERVICE} Service). Install Substrate v1.0 first; see "Pods on Agent Substrate" in the CLI README.`, 6);
+    const namespace = tenantNamespace(input.tenant);
+    const existing = await k.getJson(["namespace", namespace]);
+    const owner = existing?.metadata?.labels?.["dev.nylorun.tenant"];
+    if (existing && owner !== tenantLabel(input.tenant))
+        throw new CliError(`Namespace ${namespace} exists in ${input.context} but belongs to ${owner ?? "something else"}.`, 6);
+    await k.apply("Creating the Tenant's namespace and RBAC", [...tenantManifests(namespace, input.tenant), ...substrateManifests(namespace)]);
+    const token = await serviceAccountToken(k, namespace, pollMs);
+    let hostAddress = input.hostAddress;
+    if (!hostAddress) {
+        const lookup = await k.run(["run", "nylorun-host-lookup", "-n", namespace, "--rm", "-i", "--quiet", "--restart=Never", `--image=${PROBE_IMAGE}`, "--", "nslookup", "host.docker.internal"], { timeoutMs: cliTuning().sandbox.probeExecMs * 3 });
+        hostAddress = parseNslookup(lookup.stdout);
+        if (!hostAddress)
+            throw new CliError(`Refusing context ${input.context}: 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).`, 6);
+    }
+    const bindAddress = input.bindAddress ?? defaultBind(input.context, hostAddress);
+    const host = edgeHost(namespace);
+    const coredns = await k.getJson(["configmap", "coredns", "-n", "kube-system"]);
+    const corefile = coredns?.data?.Corefile;
+    const patched = corefile === undefined ? undefined : corefileWithEdge(corefile, host, hostAddress);
+    if (patched === undefined)
+        deps.stack.err(`Warning: could not add ${host} -> ${hostAddress} to CoreDNS in ${input.context}; actors resolve the edge only once that name resolves (add it to the cluster's DNS).`);
+    else if (patched !== corefile)
+        await k.check("Naming the edge in CoreDNS", ["patch", "configmap", "coredns", "-n", "kube-system", "--type", "merge", "-p", JSON.stringify({ data: { Corefile: patched } })]);
+    return {
+        cluster: {
+            context: input.context,
+            server,
+            dial: route.dial,
+            tlsServerName: route.tlsServerName,
+            caData,
+            namespace,
+            controllerVersion: "",
+            hostAddress,
+            bindAddress,
+            ports: input.ports,
+            networkPolicy: { enforced: false, probedAt: "" },
+            enabledAt: new Date().toISOString(),
+            backend: "substrate",
+            substrate: {
+                atespace: namespace,
+                systemNamespace: SUBSTRATE_NAMESPACE,
+                apiService: SUBSTRATE_API_SERVICE,
+                serviceAccount: SERVICE_ACCOUNT,
+                edge: { host, harnessPort: input.edgePorts.harness, gatesPort: input.edgePorts.gates },
+            },
+        },
+        token,
+    };
+}
+/**
+ * The edge's certificate and the Tenant's atespace, with the sandboxes image: `edge-cert` writes
+ * the CA and certificate next to cluster.json, and `substrate-setup` makes the atespace and its
+ * access policy as Substrate's owner client, with a 10-minute token minted from the kubeconfig.
+ */
+async function prepareSubstrate(deps, root, cluster, image) {
+    const { stack } = deps;
+    const dir = sandboxesDir(root);
+    const user = `${stack.uid}:${stack.gid}`;
+    const cert = await stack.docker.run([
+        "run", "--rm", "--user", user, "-v", `${dir}:/out`, image, "edge-cert", cluster.substrate.edge.host, "/out",
+    ]);
+    if (cert.code !== 0)
+        throw new CliError(`Making the edge's certificate failed: ${cert.stderr.trim() || cert.stdout.trim()}`, 1);
+    const k = kube(deps.kubectl, cluster.context);
+    const owner = (await k.check("Minting Substrate's owner token", [
+        "create", "token", SUBSTRATE_OWNER_ACCOUNT, "-n", SUBSTRATE_NAMESPACE, "--audience", SUBSTRATE_AUDIENCE, "--duration", "10m",
+    ])).trim();
+    const tokenFile = join(dir, "owner-token");
+    await writeFile(tokenFile, owner, { mode: 0o600 });
+    try {
+        const setup = await stack.docker.run([
+            "run", "--rm", "--user", user, "--add-host", "host.docker.internal:host-gateway",
+            "-v", `${dir}:/run/nylorun/sandboxes:ro`, "-e", "NYLORUN_SUBSTRATE_OWNER_TOKEN_FILE=/run/nylorun/sandboxes/owner-token",
+            image, "substrate-setup",
+        ]);
+        if (setup.code !== 0)
+            throw new CliError(`Making the Tenant's atespace failed: ${setup.stderr.trim() || setup.stdout.trim()}`, 1);
+        stack.err(setup.stdout.trim());
+    }
+    finally {
+        await rm(tokenFile, { force: true });
+    }
+}
 async function enable(deps, args) {
     const { stack } = deps;
-    const flags = parseStackFlags(args, { booleans: ["--no-pull"], values: ["--context", "--tenant", "--host-address", "--bind-address", "--probe-ports"] }, ENABLE_USAGE);
+    const flags = parseStackFlags(args, { booleans: ["--no-pull"], values: ["--context", "--tenant", "--backend", "--host-address", "--bind-address", "--probe-ports"] }, ENABLE_USAGE);
     if (flags.rest.length)
         throw usageError(`Usage: ${ENABLE_USAGE}`);
     const context = flags.values.get("--context");
     if (!context)
         throw usageError(`nylorun local sandbox enable needs --context <name>: the kubeconfig context to run pods in (never the current one implicitly). Usage: ${ENABLE_USAGE}`);
+    const backend = flags.values.get("--backend") ?? "agent-sandbox";
+    if (backend !== "agent-sandbox" && backend !== "substrate")
+        throw usageError(`--backend must be agent-sandbox or substrate, not ${backend}. Usage: ${ENABLE_USAGE}`);
     const hostAddress = flags.values.get("--host-address");
     const bindAddress = flags.values.get("--bind-address");
     if (hostAddress)
@@ -188,6 +302,42 @@ async function enable(deps, args) {
         gates: await pick(PREFERRED_PORTS.gates, persisted?.gatesPort),
         egress: await pick(PREFERRED_PORTS.egress, persisted?.egressPort),
     };
+    if (backend === "substrate") {
+        const edgePorts = {
+            harness: await pick(PREFERRED_EDGE_PORTS.harness, persisted?.edgeHarnessPort),
+            gates: await pick(PREFERRED_EDGE_PORTS.gates, persisted?.edgeGatesPort),
+        };
+        const images = stackImages(stack.env, { runtime: stack.runtimeVersion, studio: stack.studioVersion });
+        const installed = await installSubstrate(deps, {
+            context,
+            tenant: tenant.name,
+            ...(hostAddress ? { hostAddress } : {}),
+            ...(bindAddress ? { bindAddress } : {}),
+            ports,
+            edgePorts,
+        });
+        await writeClusterFiles(tenant.paths.root, installed.cluster, installed.token);
+        await prepareSubstrate(deps, tenant.paths.root, installed.cluster, images.sandboxes);
+        const settings = {
+            token: persisted?.token ?? randomBytes(32).toString("hex"),
+            image: images.sandboxes,
+            harnessPort: ports.harness,
+            gatesPort: ports.gates,
+            egressPort: ports.egress,
+            hostAddress: installed.cluster.hostAddress,
+            bind: installed.cluster.bindAddress,
+            edgeHarnessPort: edgePorts.harness,
+            edgeGatesPort: edgePorts.gates,
+        };
+        await restartTenant(stack, { name: tenant.name, sandboxes: settings });
+        const ready = await stack.docker.stream(tenant.compose("up", "--detach", "--wait", "--wait-timeout", String(cliTuning().sandbox.composeWaitSeconds), "sandboxes"));
+        if (ready !== 0)
+            throw new CliError(`The sandboxes service did not become ready (image ${images.sandboxes}). See "nylorun local logs sandboxes" and "nylorun local sandbox status".`, 7);
+        const c = installed.cluster;
+        stack.out(`Sandboxes ${tenant.name}  enabled on ${c.context} (backend substrate, atespace ${c.substrate.atespace}; preview)`);
+        stack.out(`Actors reach the edge ${c.substrate.edge.host} (${c.hostAddress}) on ports ${edgePorts.harness} and ${edgePorts.gates}`);
+        return 0;
+    }
     if (probePorts && [probePorts.allowed, probePorts.denied].some((port) => taken.has(port)))
         throw usageError(`--probe-ports ${probePortsFlag} overlaps the sandbox ports ${ports.harness}, ${ports.gates} and ${ports.egress}; pick two others.`);
     const images = stackImages(stack.env, { runtime: stack.runtimeVersion, studio: stack.studioVersion });
@@ -283,9 +433,17 @@ async function status(deps, args) {
     }
     else {
         stack.out(`Context     ${cluster.context}  (${cluster.server}, dialled at ${cluster.dial})`);
-        stack.out(`Namespace   ${cluster.namespace}  agent-sandbox ${cluster.controllerVersion}`);
-        stack.out(`Pods reach  ${cluster.hostAddress} ports ${cluster.ports.harness}, ${cluster.ports.gates}, ${cluster.ports.egress} (bound on ${cluster.bindAddress})`);
-        stack.out(`Policy      ${cluster.networkPolicy.enforced ? "enforced" : "NOT enforced"} (probed ${cluster.networkPolicy.probedAt})`);
+        if (cluster.backend === "substrate" && cluster.substrate) {
+            stack.out(`Namespace   ${cluster.namespace}  backend substrate (preview), atespace ${cluster.substrate.atespace}`);
+            stack.out(`Edge        ${cluster.substrate.edge.host} ports ${cluster.substrate.edge.harnessPort}, ${cluster.substrate.edge.gatesPort} (bound on ${cluster.bindAddress}, actors reach ${cluster.hostAddress})`);
+        }
+        else {
+            stack.out(`Namespace   ${cluster.namespace}  agent-sandbox ${cluster.controllerVersion}`);
+        }
+        if (cluster.backend !== "substrate") {
+            stack.out(`Pods reach  ${cluster.hostAddress} ports ${cluster.ports.harness}, ${cluster.ports.gates}, ${cluster.ports.egress} (bound on ${cluster.bindAddress})`);
+            stack.out(`Policy      ${cluster.networkPolicy.enforced ? "enforced" : "NOT enforced"} (probed ${cluster.networkPolicy.probedAt})`);
+        }
         stack.out(`Service     ${ready ? "ready" : "not ready"}${info ? "" : " (no /v1/info answer)"}`);
     }
     return ready ? 0 : 3;

package/dist/sandbox/substrate.d.ts

@@ -0,0 +1,25 @@
+/** Substrate v1.0's install: its control plane's namespace, API Service and owner client. */
+export declare const SUBSTRATE_NAMESPACE = "ate-system";
+export declare const SUBSTRATE_API_SERVICE = "api";
+export declare const SUBSTRATE_OWNER_ACCOUNT = "ate-client";
+/** The audience ate-api-server accepts: its Service's DNS name. */
+export declare const SUBSTRATE_AUDIENCE = "api.ate-system.svc";
+/** Preferred host ports for the edge: the Harness API's and the gates' TLS fronts. */
+export declare const PREFERRED_EDGE_PORTS: {
+    readonly harness: 8793;
+    readonly gates: 8794;
+};
+/** The name actors dial for the edge, unique to the Tenant's namespace. */
+export declare function edgeHost(namespace: string): string;
+/**
+ * RBAC for the sandboxes service on Substrate: in the Tenant's namespace, its state ConfigMaps
+ * and a token for its own ServiceAccount (its Substrate identity); in Substrate's namespace, a
+ * port-forward to ate-api-server; cluster-wide, reading Substrate's trust bundles.
+ */
+export declare function substrateManifests(namespace: string): object[];
+/**
+ * CoreDNS's Corefile with `host` resolving to `address` for actors: a `hosts` block in the
+ * default server block, marked so a later `enable` replaces it. Undefined when the Corefile has
+ * no `.:53` block or already has a `hosts` plugin of its own.
+ */
+export declare function corefileWithEdge(corefile: string, host: string, address: string): string | undefined;

package/dist/sandbox/substrate.js

@@ -0,0 +1,115 @@
+/**
+ * What `nylorun local sandbox enable --backend substrate` adds to a cluster that runs Agent
+ * Substrate (ADR-138, Phase 1: preview): the sandboxes service's access to Substrate's API, the
+ * Tenant's atespace (made by the sandboxes image's `substrate-setup`), and the name actors reach
+ * the edge by, in CoreDNS.
+ */
+import { SERVICE_ACCOUNT } from "./manifests.js";
+/** Substrate v1.0's install: its control plane's namespace, API Service and owner client. */
+export const SUBSTRATE_NAMESPACE = "ate-system";
+export const SUBSTRATE_API_SERVICE = "api";
+export const SUBSTRATE_OWNER_ACCOUNT = "ate-client";
+/** The audience ate-api-server accepts: its Service's DNS name. */
+export const SUBSTRATE_AUDIENCE = `${SUBSTRATE_API_SERVICE}.${SUBSTRATE_NAMESPACE}.svc`;
+/** Preferred host ports for the edge: the Harness API's and the gates' TLS fronts. */
+export const PREFERRED_EDGE_PORTS = { harness: 8793, gates: 8794 };
+/** The name actors dial for the edge, unique to the Tenant's namespace. */
+export function edgeHost(namespace) {
+    return `${namespace}.edge.nylorun.internal`;
+}
+const MANAGED = { "app.kubernetes.io/managed-by": "nylorun" };
+/**
+ * RBAC for the sandboxes service on Substrate: in the Tenant's namespace, its state ConfigMaps
+ * and a token for its own ServiceAccount (its Substrate identity); in Substrate's namespace, a
+ * port-forward to ate-api-server; cluster-wide, reading Substrate's trust bundles.
+ */
+export function substrateManifests(namespace) {
+    const subject = [{ kind: "ServiceAccount", name: SERVICE_ACCOUNT, namespace }];
+    const name = `nylorun-sandboxes-${namespace}`;
+    return [
+        {
+            apiVersion: "rbac.authorization.k8s.io/v1",
+            kind: "Role",
+            metadata: { name: `${SERVICE_ACCOUNT}-substrate`, namespace, labels: MANAGED },
+            rules: [
+                { apiGroups: [""], resources: ["configmaps"], verbs: ["get", "list", "watch", "create", "update", "delete"] },
+                { apiGroups: [""], resources: ["serviceaccounts/token"], resourceNames: [SERVICE_ACCOUNT], verbs: ["create"] },
+            ],
+        },
+        {
+            apiVersion: "rbac.authorization.k8s.io/v1",
+            kind: "RoleBinding",
+            metadata: { name: `${SERVICE_ACCOUNT}-substrate`, namespace, labels: MANAGED },
+            roleRef: { apiGroup: "rbac.authorization.k8s.io", kind: "Role", name: `${SERVICE_ACCOUNT}-substrate` },
+            subjects: subject,
+        },
+        {
+            apiVersion: "rbac.authorization.k8s.io/v1",
+            kind: "Role",
+            metadata: { name, namespace: SUBSTRATE_NAMESPACE, labels: MANAGED },
+            rules: [
+                { apiGroups: [""], resources: ["services"], resourceNames: [SUBSTRATE_API_SERVICE], verbs: ["get"] },
+                { apiGroups: [""], resources: ["pods"], verbs: ["get", "list"] },
+                { apiGroups: [""], resources: ["pods/portforward"], verbs: ["create", "get"] },
+            ],
+        },
+        {
+            apiVersion: "rbac.authorization.k8s.io/v1",
+            kind: "RoleBinding",
+            metadata: { name, namespace: SUBSTRATE_NAMESPACE, labels: MANAGED },
+            roleRef: { apiGroup: "rbac.authorization.k8s.io", kind: "Role", name },
+            subjects: subject,
+        },
+        {
+            apiVersion: "rbac.authorization.k8s.io/v1",
+            kind: "ClusterRole",
+            metadata: { name, labels: MANAGED },
+            rules: [{ apiGroups: ["certificates.k8s.io"], resources: ["clustertrustbundles"], verbs: ["get", "list", "watch"] }],
+        },
+        {
+            apiVersion: "rbac.authorization.k8s.io/v1",
+            kind: "ClusterRoleBinding",
+            metadata: { name, labels: MANAGED },
+            roleRef: { apiGroup: "rbac.authorization.k8s.io", kind: "ClusterRole", name },
+            subjects: subject,
+        },
+    ];
+}
+const BEGIN = "    # nylorun edge (nylorun local sandbox enable --backend substrate)";
+const END = "    # end nylorun edge";
+/**
+ * CoreDNS's Corefile with `host` resolving to `address` for actors: a `hosts` block in the
+ * default server block, marked so a later `enable` replaces it. Undefined when the Corefile has
+ * no `.:53` block or already has a `hosts` plugin of its own.
+ */
+export function corefileWithEdge(corefile, host, address) {
+    const lines = corefile.split("\n");
+    const start = lines.indexOf(BEGIN);
+    if (start >= 0) {
+        const end = lines.indexOf(END, start);
+        if (end < 0)
+            return undefined;
+        const ours = lines.slice(start + 1, end).filter((line) => /^\s+\d+\.\d+\.\d+\.\d+\s+\S/.test(line));
+        const entries = new Map(ours.map((line) => [line.trim().split(/\s+/)[1], line.trim().split(/\s+/)[0]]));
+        entries.set(host, address);
+        lines.splice(start, end - start + 1, ...block(entries));
+        return lines.join("\n");
+    }
+    if (lines.some((line) => /^\s*hosts(\s|$)/.test(line)))
+        return undefined;
+    const server = lines.findIndex((line) => /^\.:53\s*\{/.test(line.trim()));
+    if (server < 0)
+        return undefined;
+    lines.splice(server + 1, 0, ...block(new Map([[host, address]])));
+    return lines.join("\n");
+}
+function block(entries) {
+    return [
+        BEGIN,
+        "    hosts {",
+        ...[...entries].map(([host, address]) => `      ${address} ${host}`),
+        "      fallthrough",
+        "    }",
+        END,
+    ];
+}

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

@@ -74,6 +74,8 @@
  */
 export declare function renderComposeFile(project: string, name: string, options?: {
     sandboxes?: true;
+    /** The sandboxes container serves the edge (backend substrate, ADR-138). */
+    sandboxEdge?: true;
     harness?: "remote" | "in-process";
     restateUi?: true;
     identity?: true;

package/dist/stack/compose-file.js

@@ -327,7 +327,7 @@ ${healthcheck("runtime")}    restart: unless-stopped
     healthcheck: # /healthz needs no session; Host studio:3000 is accepted
       test: ["CMD", "node", "-e", "require('http').get({port:3000,path:'/healthz',headers:{host:'studio:3000'}},r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
 ${healthcheck("studio")}    restart: unless-stopped
-${remote ? harnessService(project) : ""}${sandboxes ? sandboxesService(project) : ""}
+${remote ? harnessService(project) : ""}${sandboxes ? sandboxesService(project, options.sandboxEdge === true) : ""}
 networks:
   default:
     name: ${project}
@@ -412,6 +412,15 @@ const SANDBOXES_GATES_PORT = `    ports:
       - "\${NYLORUN_SANDBOX_BIND:?run nylorun local sandbox enable}:\${NYLORUN_SANDBOX_GATES_PORT:?run nylorun local sandbox enable}:4100" # gates, for sandbox pods (run tokens)
       - "\${NYLORUN_SANDBOX_BIND:?run nylorun local sandbox enable}:\${NYLORUN_SANDBOX_EGRESS_PORT:?run nylorun local sandbox enable}:4200" # egress-gate, for sandbox pods (egress tokens)
 `;
+/**
+ * The edge (backend substrate, ADR-138): Substrate actors reach the Harness API and the gates
+ * over TLS that Substrate passes through; the sandboxes container terminates it and forwards to
+ * runtime:4200 and gateway:4100 on \`default\`.
+ */
+const SANDBOXES_EDGE_PORTS = `
+    ports:
+      - "\${NYLORUN_SANDBOX_BIND:?run nylorun local sandbox enable}:\${NYLORUN_SANDBOX_EDGE_HARNESS_PORT:?run nylorun local sandbox enable}:8443" # the edge: the Harness API, for actors
+      - "\${NYLORUN_SANDBOX_BIND:?run nylorun local sandbox enable}:\${NYLORUN_SANDBOX_EDGE_GATES_PORT:?run nylorun local sandbox enable}:8444" # the edge: the gates, for actors`;
 /** egress-gate (F7.2): pods' CONNECT proxy in the gateway. */
 const SANDBOXES_GATEWAY_ENV = `
       # egress-gate: the only way out of a sandbox pod, to the hosts its spec allows.
@@ -427,9 +436,9 @@ const SANDBOXES_RUNTIME_MOUNT = `
  * (NYLORUN_SANDBOX_*_PORT in .env), the Harness API's, the gates' and egress-gate's, are
  * published by the runtime and the gateway (above).
  */
-function sandboxesService(project) {
+function sandboxesService(project, edge) {
     return `
-  sandboxes: # agent-sandbox driver; the only holder of the cluster credentials; not published
+  sandboxes: # the sandboxes driver; the only holder of the cluster credentials; not published${edge ? ", but for its edge" : ""}
     image: \${NYLORUN_SANDBOXES_IMAGE:?run nylorun local sandbox enable}
     container_name: ${project}-sandboxes
     labels: *tenant
@@ -443,7 +452,7 @@ function sandboxesService(project) {
     volumes:
       # cluster.json (API server, CA, namespace) and the ServiceAccount token, read-only.
       - \${NYLORUN_HOST_ROOT:?run nylorun start}/sandboxes:/run/nylorun/sandboxes:ro
-    networks: [default] # the cluster's API server, through host.docker.internal
+    networks: [default] # the cluster's API server, through host.docker.internal${edge ? SANDBOXES_EDGE_PORTS : ""}
     healthcheck: # /ready: informers synced and the API server answers
       test: ["CMD", "/sandboxes", "healthcheck"]
 ${healthcheck("sandboxes")}    restart: unless-stopped

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

@@ -74,6 +74,12 @@ export interface SandboxStackEnv {
     hostAddress: string;
     /** Where the pod-facing ports are published (127.0.0.1 on Docker Desktop). */
     bind: string;
+    /**
+     * With the Substrate backend (ADR-138): the edge's host ports, the TLS front actors reach
+     * the Harness API and the gates through, served by the sandboxes container.
+     */
+    edgeHarnessPort?: number;
+    edgeGatesPort?: number;
 }
 export type HarnessMode = "remote" | "in-process";
 export declare function renderEnvFile(env: StackEnv): string;

package/dist/stack/env-file.js

@@ -13,6 +13,8 @@ const SANDBOX_KEYS = {
     egressPort: "NYLORUN_SANDBOX_EGRESS_PORT",
     hostAddress: "NYLORUN_SANDBOX_HOST_ADDRESS",
     bind: "NYLORUN_SANDBOX_BIND",
+    edgeHarnessPort: "NYLORUN_SANDBOX_EDGE_HARNESS_PORT",
+    edgeGatesPort: "NYLORUN_SANDBOX_EDGE_GATES_PORT",
 };
 const KEYS = {
     runtimePort: "NYLORUN_PORT",
@@ -120,6 +122,13 @@ export function renderEnvFile(env) {
                 sandboxLine("egressPort"),
                 sandboxLine("hostAddress"),
                 sandboxLine("bind"),
+                ...(sandboxes.edgeHarnessPort && sandboxes.edgeGatesPort
+                    ? [
+                        "# The edge (backend substrate): the TLS ports actors reach the Runtime through.",
+                        sandboxLine("edgeHarnessPort"),
+                        sandboxLine("edgeGatesPort"),
+                    ]
+                    : []),
                 "",
             ]
             : []),
@@ -161,7 +170,12 @@ function parseSandboxes(values) {
         return undefined;
     if (!hostAddress || !IPV4.test(hostAddress) || !bind || !IPV4.test(bind))
         return undefined;
-    return { token, image, harnessPort, gatesPort, egressPort, hostAddress, bind };
+    const edgeHarnessPort = port(values.get(SANDBOX_KEYS.edgeHarnessPort));
+    const edgeGatesPort = port(values.get(SANDBOX_KEYS.edgeGatesPort));
+    return {
+        token, image, harnessPort, gatesPort, egressPort, hostAddress, bind,
+        ...(edgeHarnessPort && edgeGatesPort ? { edgeHarnessPort, edgeGatesPort } : {}),
+    };
 }
 export function parsePersisted(text) {
     const values = parseEnvLines(text);

package/dist/stack/prepare.js

@@ -102,6 +102,7 @@ export async function prepareStack(input) {
     await writeFileMode(paths.compose, renderComposeFile(input.project, input.name, {
         harness: env.harness,
         ...(env.sandboxes ? { sandboxes: true } : {}),
+        ...(env.sandboxes?.edgeHarnessPort ? { sandboxEdge: true } : {}),
         ...(env.restateUi ? { restateUi: true } : {}),
         // The trusted issuers, when the operator wrote an identity file; a change takes a restart.
         ...(existsSync(paths.identity) ? { identity: true } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylorun",
-  "version": "0.28.0-beta",
+  "version": "0.29.1-beta",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Set up and run local Nylorun Tenants (Runtime and Studio) with Docker Compose, and act on a Tenant through its Runtime and Management APIs",
@@ -30,9 +30,9 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nylorun/admin": "0.19.14-beta",
-    "@nylorun/agents": "0.36.1-beta",
-    "@nylorun/core": "0.38.0-beta"
+    "@nylorun/admin": "0.19.15-beta",
+    "@nylorun/agents": "0.36.2-beta",
+    "@nylorun/core": "0.39.0-beta"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "1.3.0",
@@ -46,7 +46,7 @@
     "nylo": "dist/nylo.js"
   },
   "nylorun": {
-    "runtime": "0.44.2-beta",
-    "studio": "0.35.7-beta"
+    "runtime": "0.45.1-beta",
+    "studio": "0.35.8-beta"
   }
 }