nylorun 0.7.0-beta → 0.8.0-beta

package/dist/stack/compose-file.js

@@ -6,8 +6,8 @@ import { PINNED_IMAGES } from "./images.js";
  * 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
@@ -26,8 +26,8 @@ import { PINNED_IMAGES } from "./images.js";
  * 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
@@ -36,8 +36,44 @@ import { PINNED_IMAGES } from "./images.js";
  * 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 function renderComposeFile(project, name) {
+export function renderComposeFile(project, name, options = {}) {
+    const sandboxes = options.sandboxes === true;
+    const remote = (options.harness ?? "remote") === "remote";
+    const restateUi = options.restateUi === true;
     return `# Written by \`nylorun start\`; rewritten on every start. Settings live in .env.
 name: ${project}
 
@@ -58,6 +94,7 @@ services:
       POSTGRES_INITDB_ARGS: "--locale=C" # C collation for the whole database
     volumes:
       - postgres:/var/lib/postgresql/data
+    networks: [store]
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U nylorun -d nylorun"]
       interval: 2s
@@ -75,9 +112,7 @@ services:
     volumes:
       - restate:/restate-data
       - \${NYLORUN_HOST_ROOT:?run nylorun start}/docker/restate-identity.pem:/run/nylorun/restate-identity.pem:ro
-    ports:
-      - "127.0.0.1:\${NYLORUN_RESTATE_PORT:?run nylorun start}:9070" # Restate UI and admin, for debugging
-    healthcheck:
+${restateUi ? RESTATE_UI : RESTATE_CLOSED}    healthcheck:
       test: ["CMD", "curl", "-fsS", "http://localhost:9070/health"]
       interval: 2s
       timeout: 5s
@@ -94,15 +129,36 @@ services:
     # (e.g. /data) is root-owned and s2-lite cannot write it.
     volumes:
       - s2-lite:/home/nonroot
+    networks: [store]
     # The s2 image has no shell or HTTP client, so it has no health check;
     # the Runtime's /ready covers it.
     restart: unless-stopped
 
-  gateway: # the Model and Tool Gates and keys: the vault key, credentials, signing, outbound calls; not published
+  rustfs: # the Object store (D35); not published, only the runtime and the gateway hold its credential
+    image: ${PINNED_IMAGES.rustfs}
+    container_name: ${project}-rustfs
+    labels: *tenant
+    environment:
+      RUSTFS_ACCESS_KEY: nylorun
+      RUSTFS_SECRET_KEY: \${NYLORUN_OBJECT_STORE_SECRET_KEY:?run nylorun start}
+      RUSTFS_CONSOLE_ENABLE: "false" # no web console: clients go through the Runtime
+      RUSTFS_OBS_LOG_DIRECTORY: "" # log to stdout (nylorun logs rustfs)
+    # The image runs as uid 10001 and owns /data, which Docker copies into the new volume.
+    volumes:
+      - rustfs:/data
+    networks: [store]
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:9000/health"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+    restart: unless-stopped
+
+  gateway: # the Model and Tool Gates and keys: the vault key, credentials, signing, outbound calls; not published${sandboxes ? ", but for sandbox pods" : ""}
     image: \${NYLORUN_RUNTIME_IMAGE:?run nylorun start}
     container_name: ${project}-gateway
     labels: *tenant
-    command: ["--service", "gates,keys"]
+    command: ["--service", "gates,keys${sandboxes ? ",egress" : ""}"]
     user: "\${NYLORUN_UID:?run nylorun start}:\${NYLORUN_GID:?run nylorun start}"
     depends_on:
       postgres: { condition: service_healthy }
@@ -110,17 +166,23 @@ services:
       NYLORUN_HOME: /nylorun
       NYLORUN_PACKING: combined
       NYLORUN_GATES_LISTEN_PORT: "4100"
-      NYLORUN_GATES_ALLOWED_HOSTS: gateway:4100
+      NYLORUN_GATES_ALLOWED_HOSTS: gateway:4100${sandboxes ? SANDBOXES_GATES_HOST : ""}
       NYLORUN_GATES_TOKEN: \${NYLORUN_GATES_TOKEN:?run nylorun start}
       NYLORUN_DATABASE_URL: postgres://nylorun:\${NYLORUN_POSTGRES_PASSWORD}@postgres:5432/nylorun
+      # The Object store, where model-gate will read file parts (F8.1).
+      NYLORUN_OBJECT_STORE_ENDPOINT: http://rustfs:9000
+      NYLORUN_OBJECT_STORE_ACCESS_KEY: nylorun
+      NYLORUN_OBJECT_STORE_SECRET_KEY: \${NYLORUN_OBJECT_STORE_SECRET_KEY:?run nylorun start}
       # Action endpoints on this machine: \`localhost\` in a registered URL means the Docker host.
-      NYLORUN_ENDPOINT_LOOPBACK: docker-host
+      NYLORUN_ENDPOINT_LOOPBACK: docker-host${sandboxes ? SANDBOXES_GATEWAY_ENV : ""}
     extra_hosts:
       host.docker.internal: host-gateway # model servers, MCP servers and Action endpoints on this machine
     volumes:
       # The Tenant's homes and its vault key only, read-only.
       - \${NYLORUN_HOST_ROOT:?run nylorun start}/tenant:/nylorun/tenant:ro
       - \${NYLORUN_HOST_ROOT:?run nylorun start}/keys:/nylorun/keys:ro
+${sandboxes ? SANDBOXES_GATES_PORT : ""}    # Egress and the stores; the harness reaches its gates on \`harness\`.
+    networks: [default, store, harness]
     healthcheck:
       test: ["CMD", "node", "-e", "fetch('http://localhost:4100/ready').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
       interval: 2s
@@ -138,6 +200,7 @@ services:
       postgres: { condition: service_healthy }
       restate: { condition: service_healthy }
       s2-lite: { condition: service_started }
+      rustfs: { condition: service_healthy }
     environment:
       NYLORUN_HOME: /nylorun
       NYLORUN_PACKING: combined
@@ -168,8 +231,18 @@ services:
       NYLORUN_S2_ENDPOINT: http://s2-lite:80
       NYLORUN_S2_TOKEN: ignored # s2-lite has no access tokens yet
       NYLORUN_WORKSPACE_STORE_URL: file:///workspaces
+      # The Object store, through the BlobStore seam's s3 adapter; the runtime creates the bucket.
+      NYLORUN_OBJECT_STORE_ENDPOINT: http://rustfs:9000
+      NYLORUN_OBJECT_STORE_ACCESS_KEY: nylorun
+      NYLORUN_OBJECT_STORE_SECRET_KEY: \${NYLORUN_OBJECT_STORE_SECRET_KEY:?run nylorun start}
       # Action endpoints on this machine: \`localhost\` in a registered URL means the Docker host.
       NYLORUN_ENDPOINT_LOOPBACK: docker-host
+      # Agent turns, MCP servers and workspaces run in the harness container, which connects to
+      # this listener with NYLORUN_HARNESS_TOKEN. NYLORUN_HARNESS=in-process in .env rolls back.
+      NYLORUN_HARNESS: \${NYLORUN_HARNESS:-remote}
+      NYLORUN_HARNESS_LISTEN_PORT: "4200"
+      NYLORUN_HARNESS_ALLOWED_HOSTS: runtime:4200${sandboxes ? SANDBOXES_HARNESS_HOST : ""}
+      NYLORUN_HARNESS_TOKEN: \${NYLORUN_HARNESS_TOKEN:?run nylorun start}${sandboxes ? SANDBOXES_RUNTIME_ENV : ""}
     extra_hosts:
       host.docker.internal: host-gateway # the Docker host, also on Linux Docker Engine
     volumes:
@@ -183,11 +256,14 @@ services:
       - type: tmpfs
         target: /nylorun/docker
         read_only: true
-        tmpfs: { size: 4096, mode: 0755 } # empty, and listable by the runtime user
+        tmpfs: { size: 4096, mode: 0755 } # empty, and listable by the runtime user${sandboxes ? SANDBOXES_RUNTIME_MOUNT : ""}
       - workspaces:/workspaces
+      # Plugin roots on this machine, at their own path (as for the harness), for NYLORUN_HARNESS=in-process.
+      - \${NYLORUN_HOST_ROOT:?run nylorun start}/plugins:\${NYLORUN_HOST_ROOT:?run nylorun start}/plugins:ro
+    networks: [default, store, harness]
     ports:
       - "127.0.0.1:\${NYLORUN_PORT:?run nylorun start}:4000" # Tenant API, SSE, browsers
-      - "127.0.0.1:\${NYLORUN_ADMIN_PORT:?run nylorun start}:4001" # Admin API (operators only)
+      - "127.0.0.1:\${NYLORUN_ADMIN_PORT:?run nylorun start}:4001" # Admin API (operators only)${sandboxes ? SANDBOXES_RUNTIME_PORT : ""}
     healthcheck: # liveness: a Tenant that cannot open is reported by nylorun start from the Admin status, not by a 300 s wait
       test: ["CMD", "node", "-e", "fetch('http://localhost:4000/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
       interval: 2s
@@ -217,6 +293,7 @@ services:
       NYLORUN_STUDIO_ANALYTICS_ID: \${NYLORUN_STUDIO_ANALYTICS_ID:-}
     volumes:
       - \${NYLORUN_HOST_ROOT}/host-credentials.json:/run/nylorun/host-credentials.json:ro
+    networks: [default]
     ports:
       - "127.0.0.1:\${NYLORUN_STUDIO_PORT:?run nylorun start}:3000" # opened as http://localhost:<port>
     healthcheck: # /healthz needs no session; Host studio:3000 is accepted
@@ -225,16 +302,131 @@ services:
       timeout: 5s
       retries: 30
     restart: unless-stopped
-
+${remote ? harnessService(project) : ""}${sandboxes ? sandboxesService(project) : ""}
 networks:
   default:
     name: ${project}
     labels: *tenant
+  store: # the stores: no egress, no published port
+    name: ${project}-store
+    internal: true
+    labels: *tenant
+  harness: # the harness reaches the runtime's Harness API and the gateway only (egress for MCP servers and bash)
+    name: ${project}-harness
+    labels: *tenant
 
 volumes:
   postgres: { name: ${project}-postgres, labels: *tenant }
   restate: { name: ${project}-restate, labels: *tenant }
   s2-lite: { name: ${project}-s2-lite, labels: *tenant }
+  rustfs: { name: ${project}-rustfs, labels: *tenant }
   workspaces: { name: ${project}-workspaces, labels: *tenant }
 `;
 }
+/** Restate on the stores' network only: its admin port (the UI) is not published. */
+const RESTATE_CLOSED = `    networks: [store] # admin and UI not published: nylorun start --restate-ui
+`;
+/** Restate's admin port and UI on loopback (`--restate-ui`): it must join `default` to be published. */
+const RESTATE_UI = `    networks: [store, default]
+    ports:
+      - "127.0.0.1:\${NYLORUN_RESTATE_PORT:?run nylorun start}:9070" # Restate UI and admin (unauthenticated): nylorun start --restate-ui
+`;
+/**
+ * The harness service (F6.2): agent turns, MCP stdio servers and workspaces, apart from core.
+ * It holds the harness token only; models and remote MCP servers are reached through the
+ * gateway with each run's token. Healthy once connected to core's Harness API.
+ */
+function harnessService(project) {
+    return `
+  harness: # agent turns, MCP servers and workspaces; holds only the harness token; not published
+    image: \${NYLORUN_RUNTIME_IMAGE:?run nylorun start}
+    container_name: ${project}-harness
+    labels: *tenant
+    command: ["--service", "harness"]
+    user: "\${NYLORUN_UID:?run nylorun start}:\${NYLORUN_GID:?run nylorun start}"
+    depends_on:
+      runtime: { condition: service_healthy }
+      gateway: { condition: service_healthy }
+    environment:
+      NYLORUN_HARNESS_URL: ws://runtime:4200/nylorun/harness/v1
+      NYLORUN_HARNESS_TOKEN: \${NYLORUN_HARNESS_TOKEN:?run nylorun start}
+      NYLORUN_GATES_URL: http://gateway:4100
+      NYLORUN_HARNESS_ROOT: /harness
+    volumes:
+      # The Tenant's workspaces, plugin data and the homes of MCP stdio servers; nothing else.
+      - \${NYLORUN_HOST_ROOT:?run nylorun start}/tenant/sandboxes:/harness/sandboxes
+      - \${NYLORUN_HOST_ROOT:?run nylorun start}/tenant/plugin-data:/harness/plugin-data
+      - \${NYLORUN_HOST_ROOT:?run nylorun start}/tenant/home:/harness/home
+      - \${NYLORUN_HOST_ROOT:?run nylorun start}/tenant/tmp:/harness/tmp
+      # Plugin roots on this machine, read-only, at their own path: agents name them so.
+      - \${NYLORUN_HOST_ROOT:?run nylorun start}/plugins:\${NYLORUN_HOST_ROOT:?run nylorun start}/plugins:ro
+    networks: [harness]
+    healthcheck: # healthy once connected to core's Harness API
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:4300/health').then(r=>r.json()).then(b=>process.exit(b.connected?0:1),()=>process.exit(1))"]
+      interval: 2s
+      timeout: 5s
+      retries: 90
+    restart: unless-stopped
+`;
+}
+/**
+ * The runtime reaches the sandboxes service on the Compose network with its token, and serves
+ * the Harness API to sandbox pods (F7.2) on the Docker host's address.
+ */
+const SANDBOXES_RUNTIME_ENV = `
+      # The sandboxes service (nylorun sandbox enable): pods on the Tenant's cluster.
+      NYLORUN_SANDBOXES_URL: http://sandboxes:4300
+      NYLORUN_SANDBOXES_TOKEN: \${NYLORUN_SANDBOXES_TOKEN:?run nylorun sandbox enable}
+      NYLORUN_SANDBOX_HARNESS_IMAGE: \${NYLORUN_RUNTIME_IMAGE:?run nylorun start} # pods copy the engine from it`;
+/** Pods join and connect to the Harness API at the Docker host's address. */
+const SANDBOXES_HARNESS_HOST = ",\${NYLORUN_SANDBOX_HOST_ADDRESS:?run nylorun sandbox enable}:\${NYLORUN_SANDBOX_HARNESS_PORT:?run nylorun sandbox enable}";
+/** The Harness API, published for sandbox pods. */
+const SANDBOXES_RUNTIME_PORT = `
+      - "\${NYLORUN_SANDBOX_BIND:?run nylorun sandbox enable}:\${NYLORUN_SANDBOX_HARNESS_PORT:?run nylorun sandbox enable}:4200" # Harness API, for sandbox pods`;
+/** The gates accept the pods' Host; their calls carry run tokens. */
+const SANDBOXES_GATES_HOST = ",\${NYLORUN_SANDBOX_HOST_ADDRESS:?run nylorun sandbox enable}:\${NYLORUN_SANDBOX_GATES_PORT:?run nylorun sandbox enable}";
+/** The gates and egress-gate, published for sandbox pods. */
+const SANDBOXES_GATES_PORT = `    ports:
+      - "\${NYLORUN_SANDBOX_BIND:?run nylorun sandbox enable}:\${NYLORUN_SANDBOX_GATES_PORT:?run nylorun sandbox enable}:4100" # gates, for sandbox pods (run tokens)
+      - "\${NYLORUN_SANDBOX_BIND:?run nylorun sandbox enable}:\${NYLORUN_SANDBOX_EGRESS_PORT:?run nylorun sandbox enable}:4200" # egress-gate, for sandbox pods (egress tokens)
+`;
+/** 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.
+      NYLORUN_EGRESS_LISTEN_PORT: "4200"`;
+/** Empty and read-only over the cluster credentials: only the sandboxes service reads them. */
+const SANDBOXES_RUNTIME_MOUNT = `
+      - type: tmpfs
+        target: /nylorun/sandboxes
+        read_only: true
+        tmpfs: { size: 4096, mode: 0755 } # empty, and listable by the runtime user`;
+/**
+ * The sandboxes service. The pod-facing ports `nylorun sandbox enable` records
+ * (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) {
+    return `
+  sandboxes: # agent-sandbox driver; the only holder of the cluster credentials; not published
+    image: \${NYLORUN_SANDBOXES_IMAGE:?run nylorun sandbox enable}
+    container_name: ${project}-sandboxes
+    labels: *tenant
+    user: "\${NYLORUN_UID:?run nylorun start}:\${NYLORUN_GID:?run nylorun start}" # reads the 0600 token
+    environment:
+      NYLORUN_SANDBOXES_TOKEN: \${NYLORUN_SANDBOXES_TOKEN:?run nylorun sandbox enable}
+      NYLORUN_SANDBOXES_DIR: /run/nylorun/sandboxes
+      NYLORUN_SANDBOXES_LISTEN: ":4300"
+    extra_hosts:
+      host.docker.internal: host-gateway # the API server when the kubeconfig names this machine's loopback
+    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
+    healthcheck: # /ready: informers synced and the API server answers
+      test: ["CMD", "/sandboxes", "healthcheck"]
+      interval: 5s
+      timeout: 5s
+      retries: 24
+    restart: unless-stopped
+`;
+}

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

@@ -14,11 +14,32 @@ export interface StackEnv {
     adminPort: number;
     /** Published Studio port (loopback). */
     studioPort: number;
-    /** Published Restate UI and admin port (loopback). */
+    /** Restate UI and admin port (loopback), published only with `restateUi`. */
     restatePort: number;
+    /**
+     * `NYLORUN_RESTATE_UI`: `1` publishes Restate's UI and admin port (unauthenticated) for this
+     * start (`nylorun start --restate-ui`); `0` keeps it closed. Decided again on every start.
+     */
+    restateUi: boolean;
     postgresPassword: string;
     /** The token the runtime presents to the gateway (`NYLORUN_GATES_TOKEN`), 32 bytes as hex. */
     gatesToken: string;
+    /**
+     * The harness's credential for core's Harness API (`NYLORUN_HARNESS_TOKEN`), 32 bytes as hex:
+     * given only to the runtime (which checks it) and the harness.
+     */
+    harnessToken: string;
+    /**
+     * `NYLORUN_HARNESS`: `remote` (the harness container runs agent turns, MCP servers and
+     * workspaces) or `in-process` (the runtime does, without a harness container). Kept across
+     * starts; edit `.env` to roll back.
+     */
+    harness: HarnessMode;
+    /**
+     * RustFS's secret key (`NYLORUN_OBJECT_STORE_SECRET_KEY`), 32 bytes as hex: the Object store's
+     * credential, given only to the runtime and the gateway.
+     */
+    objectStoreSecretKey: string;
     /** `publickeyv1_...` of `docker/restate-identity.pem`. */
     restateIdentityKey: string;
     uid: number;
@@ -41,7 +62,27 @@ export interface StackEnv {
      * always includes `project`, the Project link's principal.
      */
     derivedPrincipals: string;
+    /** Present once `nylorun sandbox enable` ran for the Tenant (F7.2). */
+    sandboxes?: SandboxStackEnv;
+}
+/**
+ * The sandboxes service's settings (`nylorun sandbox enable`): its bearer token (only the
+ * runtime presents it), its image, and the host ports pods reach (Harness API, gates,
+ * egress) on the host address, published on the bind address. The ports persist.
+ */
+export interface SandboxStackEnv {
+    /** NYLORUN_SANDBOXES_TOKEN, 32 bytes as hex. */
+    token: string;
+    image: string;
+    harnessPort: number;
+    gatesPort: number;
+    egressPort: number;
+    /** The Docker host as pods reach it (192.168.65.254 on Docker Desktop). */
+    hostAddress: string;
+    /** Where the pod-facing ports are published (127.0.0.1 on Docker Desktop). */
+    bind: string;
 }
+export type HarnessMode = "remote" | "in-process";
 export declare function renderEnvFile(env: StackEnv): string;
 /**
  * `NYLORUN_DERIVED_PRINCIPALS`: comma-separated principal ids, as the Runtime accepts them
@@ -56,10 +97,16 @@ export interface PersistedStackEnv {
     adminPort?: number;
     studioPort?: number;
     restatePort?: number;
+    /** Whether the last start published Restate's UI (`NYLORUN_RESTATE_UI=1`). */
+    restateUi?: boolean;
     postgresPassword?: string;
     gatesToken?: string;
+    harnessToken?: string;
+    harness?: HarnessMode;
+    objectStoreSecretKey?: string;
     /** Validated origins; absent when the line is missing (an older .env). */
     studioFrameAncestors?: string[];
     derivedPrincipals?: string[];
+    sandboxes?: SandboxStackEnv;
 }
 export declare function parsePersisted(text: string): PersistedStackEnv;

package/dist/stack/env-file.js

@@ -9,13 +9,26 @@ export const DEFAULT_STUDIO_FRAME_ANCESTORS = [
     "nylorun://localhost",
     "http://nylorun.localhost",
 ];
+const SANDBOX_KEYS = {
+    token: "NYLORUN_SANDBOXES_TOKEN",
+    image: "NYLORUN_SANDBOXES_IMAGE",
+    harnessPort: "NYLORUN_SANDBOX_HARNESS_PORT",
+    gatesPort: "NYLORUN_SANDBOX_GATES_PORT",
+    egressPort: "NYLORUN_SANDBOX_EGRESS_PORT",
+    hostAddress: "NYLORUN_SANDBOX_HOST_ADDRESS",
+    bind: "NYLORUN_SANDBOX_BIND",
+};
 const KEYS = {
     runtimePort: "NYLORUN_PORT",
     adminPort: "NYLORUN_ADMIN_PORT",
     studioPort: "NYLORUN_STUDIO_PORT",
     restatePort: "NYLORUN_RESTATE_PORT",
+    restateUi: "NYLORUN_RESTATE_UI",
     postgresPassword: "NYLORUN_POSTGRES_PASSWORD",
     gatesToken: "NYLORUN_GATES_TOKEN",
+    harnessToken: "NYLORUN_HARNESS_TOKEN",
+    harness: "NYLORUN_HARNESS",
+    objectStoreSecretKey: "NYLORUN_OBJECT_STORE_SECRET_KEY",
     restateIdentityKey: "NYLORUN_RESTATE_IDENTITY_KEY",
     uid: "NYLORUN_UID",
     gid: "NYLORUN_GID",
@@ -42,17 +55,25 @@ function unquote(value) {
     return trimmed;
 }
 export function renderEnvFile(env) {
-    const line = (field) => `${KEYS[field]}=${quote(KEYS[field], String(env[field]))}`;
+    const line = (field) => {
+        const value = env[field];
+        return `${KEYS[field]}=${quote(KEYS[field], typeof value === "boolean" ? (value ? "1" : "0") : String(value))}`;
+    };
+    const sandboxes = env.sandboxes;
+    const sandboxLine = (field) => `${SANDBOX_KEYS[field]}=${quote(SANDBOX_KEYS[field], String(sandboxes[field]))}`;
     return [
-        "# Written by `nylorun start`. Mode 0600: holds the Postgres password and the",
-        "# gates token. Ports, the password and the token are kept across starts;",
-        "# images, UID/GID and the Host root are refreshed on every start.",
+        "# Written by `nylorun start`. Mode 0600: holds the Postgres password, the gates",
+        "# token and the Object store's secret key. Ports and secrets are kept across",
+        "# starts; images, UID/GID and the Host root are refreshed on every start.",
         "",
         "# Published on 127.0.0.1; clients use http://localhost:<port>.",
         line("runtimePort"),
         line("adminPort"),
         line("studioPort"),
+        "# Restate's UI and admin (unauthenticated) are published only with",
+        "# nylorun start --restate-ui (or NYLORUN_RESTATE_UI=1); decided on every start.",
         line("restatePort"),
+        line("restateUi"),
         "",
         line("postgresPassword"),
         "",
@@ -60,6 +81,16 @@ export function renderEnvFile(env) {
         "# model call.",
         line("gatesToken"),
         "",
+        "# The harness container presents this token to the runtime's Harness API; it",
+        "# holds no other credential. NYLORUN_HARNESS=in-process runs agent turns, MCP",
+        "# servers and workspaces in the runtime container instead (rollback); kept.",
+        line("harnessToken"),
+        line("harness"),
+        "",
+        "# RustFS (the Object store) accepts this secret key; only the runtime and the",
+        "# gateway receive it.",
+        line("objectStoreSecretKey"),
+        "",
         "# Restate signs requests to the Runtime's Worker endpoint with the private",
         "# key in restate-identity.pem; the Runtime accepts only this public key.",
         line("restateIdentityKey"),
@@ -87,6 +118,20 @@ export function renderEnvFile(env) {
         line("tenantName"),
         line("derivedPrincipals"),
         "",
+        ...(sandboxes
+            ? [
+                "# Sandboxes (nylorun sandbox enable): the runtime's token for the sandboxes",
+                "# service, its image, and the host ports pods reach on the host address.",
+                sandboxLine("token"),
+                sandboxLine("image"),
+                sandboxLine("harnessPort"),
+                sandboxLine("gatesPort"),
+                sandboxLine("egressPort"),
+                sandboxLine("hostAddress"),
+                sandboxLine("bind"),
+                "",
+            ]
+            : []),
     ].join("\n");
 }
 /**
@@ -123,6 +168,24 @@ function port(value) {
     const n = Number(value);
     return n >= 1 && n <= 65535 ? n : undefined;
 }
+const IPV4 = /^(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)$/;
+/** The sandboxes section, when complete and valid. */
+function parseSandboxes(values) {
+    const token = values.get(SANDBOX_KEYS.token);
+    const image = values.get(SANDBOX_KEYS.image);
+    const harnessPort = port(values.get(SANDBOX_KEYS.harnessPort));
+    const gatesPort = port(values.get(SANDBOX_KEYS.gatesPort));
+    const egressPort = port(values.get(SANDBOX_KEYS.egressPort));
+    const hostAddress = values.get(SANDBOX_KEYS.hostAddress);
+    const bind = values.get(SANDBOX_KEYS.bind);
+    if (!token || !/^[0-9a-f]{64,}$/i.test(token) || !image)
+        return undefined;
+    if (!harnessPort || !gatesPort || !egressPort)
+        return undefined;
+    if (!hostAddress || !IPV4.test(hostAddress) || !bind || !IPV4.test(bind))
+        return undefined;
+    return { token, image, harnessPort, gatesPort, egressPort, hostAddress, bind };
+}
 export function parsePersisted(text) {
     const values = parseEnvLines(text);
     const out = {};
@@ -138,12 +201,23 @@ export function parsePersisted(text) {
     const restatePort = port(values.get(KEYS.restatePort));
     if (restatePort)
         out.restatePort = restatePort;
+    if (values.get(KEYS.restateUi) === "1")
+        out.restateUi = true;
     const password = values.get(KEYS.postgresPassword);
     if (password && /^[A-Za-z0-9]{16,}$/.test(password))
         out.postgresPassword = password;
     const gatesToken = values.get(KEYS.gatesToken);
     if (gatesToken && /^[0-9a-f]{64,}$/i.test(gatesToken))
         out.gatesToken = gatesToken;
+    const harnessToken = values.get(KEYS.harnessToken);
+    if (harnessToken && /^[0-9a-f]{64,}$/i.test(harnessToken))
+        out.harnessToken = harnessToken;
+    const harness = values.get(KEYS.harness);
+    if (harness === "remote" || harness === "in-process")
+        out.harness = harness;
+    const objectStoreSecretKey = values.get(KEYS.objectStoreSecretKey);
+    if (objectStoreSecretKey && /^[0-9a-f]{64}$/i.test(objectStoreSecretKey))
+        out.objectStoreSecretKey = objectStoreSecretKey;
     const principals = values.get(KEYS.derivedPrincipals);
     if (principals !== undefined) {
         try {
@@ -153,6 +227,9 @@ export function parsePersisted(text) {
             /* rewritten from the default on the next start */
         }
     }
+    const sandboxes = parseSandboxes(values);
+    if (sandboxes)
+        out.sandboxes = sandboxes;
     const ancestors = values.get(KEYS.studioFrameAncestors);
     if (ancestors !== undefined) {
         try {

package/dist/stack/host-files.js

@@ -26,7 +26,17 @@ async function writeAtomic(path, text) {
 }
 /** The Host root layout, mode 0700. */
 export async function ensureHostLayout(paths) {
-    for (const dir of [paths.root, paths.home, paths.tmp, paths.tenant, paths.keys, paths.docker])
+    // The harness container's mounts exist before Compose binds them (else Docker makes them as root).
+    for (const dir of [
+        paths.root,
+        paths.home,
+        paths.tmp,
+        paths.tenant,
+        ...Object.values(paths.harness),
+        paths.plugins,
+        paths.keys,
+        paths.docker,
+    ])
         await mkdir(dir, { recursive: true, mode: 0o700 });
 }
 export async function readHostConfig(paths) {

package/dist/stack/images.d.ts

@@ -1,20 +1,26 @@
 /**
  * Images a local Tenant runs. The Runtime and Studio tags are pinned by this
  * CLI release; `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them
- * (local builds, CI images). Postgres, Restate and s2-lite are the official
- * images, pinned here.
+ * (local builds, CI images). The sandboxes service (`nylorun sandbox enable`) is
+ * versioned with the Runtime: `ghcr.io/nylorun/sandboxes:<runtime pin>`, or
+ * `NYLORUN_SANDBOXES_IMAGE`. Postgres, Restate, s2-lite and RustFS are the
+ * official images, pinned here; RustFS (the Object store, D35) by digest as well, so
+ * it is upgraded only on purpose.
  */
 export declare const PINNED_IMAGES: {
     readonly postgres: "postgres:17.11";
     readonly restate: "docker.restate.dev/restatedev/restate:1.7.12";
     readonly s2: "ghcr.io/s2-streamstore/s2:0.43.0";
+    readonly rustfs: "rustfs/rustfs:1.0.1@sha256:1803faef57627e2d9c2e7d89d655d712ddded5389040054987163043fecb6a3c";
 };
 export interface StackImages {
     runtime: string;
     studio: string;
+    sandboxes: string;
     postgres: string;
     restate: string;
     s2: string;
+    rustfs: string;
 }
 /** `NYLORUN_RUNTIME_IMAGE` names the Runtime image, so its version is unknown here. */
 export declare function runtimeImageOverridden(env: Readonly<Record<string, string | undefined>>): boolean;

package/dist/stack/images.js

@@ -2,13 +2,17 @@ import { pinnedVersion } from "./versions.js";
 /**
  * Images a local Tenant runs. The Runtime and Studio tags are pinned by this
  * CLI release; `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them
- * (local builds, CI images). Postgres, Restate and s2-lite are the official
- * images, pinned here.
+ * (local builds, CI images). The sandboxes service (`nylorun sandbox enable`) is
+ * versioned with the Runtime: `ghcr.io/nylorun/sandboxes:<runtime pin>`, or
+ * `NYLORUN_SANDBOXES_IMAGE`. Postgres, Restate, s2-lite and RustFS are the
+ * official images, pinned here; RustFS (the Object store, D35) by digest as well, so
+ * it is upgraded only on purpose.
  */
 export const PINNED_IMAGES = {
     postgres: "postgres:17.11",
     restate: "docker.restate.dev/restatedev/restate:1.7.12",
     s2: "ghcr.io/s2-streamstore/s2:0.43.0",
+    rustfs: "rustfs/rustfs:1.0.1@sha256:1803faef57627e2d9c2e7d89d655d712ddded5389040054987163043fecb6a3c",
 };
 function override(env, name) {
     const value = env[name]?.trim();
@@ -27,6 +31,8 @@ export function stackImages(env, versions = {
             `ghcr.io/nylorun/runtime:${versions.runtime}`,
         studio: override(env, "NYLORUN_STUDIO_IMAGE") ??
             `ghcr.io/nylorun/studio:${versions.studio}`,
+        sandboxes: override(env, "NYLORUN_SANDBOXES_IMAGE") ??
+            `ghcr.io/nylorun/sandboxes:${versions.runtime}`,
         ...PINNED_IMAGES,
     };
 }

package/dist/stack/index.d.ts

@@ -7,6 +7,9 @@ export type { Check, DockerChecks } from "./docker.js";
 export declare function defaultStackDeps(env: Readonly<Record<string, string | undefined>>): StackDeps;
 /** Entry for `nylorun start|stop|status|logs|reset|studio|ls|delete`. */
 export declare function stackCommand(name: string, args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
+/** Entry for `nylorun sandbox ls|rm`. */
+export declare function sandboxCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>): Promise<number>;
+export { sandboxUsage } from "./sandbox.js";
 /** `nylorun studio`, landing on `next` when given, else on the Tenant's page. */
 export declare function studioCommand(args: readonly string[], env: Readonly<Record<string, string | undefined>>, options?: {
     next?: string;