nylorun 0.7.0-beta → 0.9.0-beta

package/dist/stack/compose-file.js

@@ -6,16 +6,15 @@ 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
  * database with C collation (`--locale=C`) and runs with `wal_level=logical`: the stream
  * relay feeds s2-lite from the record over logical replication (Durable Streams), and
  * `max_slot_wal_keep_size` caps the WAL a stuck relay can hold. The Runtime creates the
- * Tenant on its first start, with its name (`NYLORUN_TENANT_NAME`) and the derived
- * principals of `NYLORUN_DERIVED_PRINCIPALS` (`project` for the Project link).
+ * Tenant on its first start, with its name (`NYLORUN_TENANT_NAME`).
  *
  * Restate signs requests to the Worker endpoint with the private key in
  * `docker/restate-identity.pem`, mounted read-only; the Runtime gets the public
@@ -26,8 +25,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 +35,48 @@ 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`).
+ *
+ * With `identity` (when `<Host root>/identity.yaml` exists) the runtime reads its trusted issuers
+ * from it, through the Host root mount (NYLORUN_IDENTITY_FILE=/nylorun/identity.yaml).
  */
-export function renderComposeFile(project, name) {
+export function renderComposeFile(project, name, options = {}) {
+    const sandboxes = options.sandboxes === true;
+    const identity = options.identity === 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 +97,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 +115,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 +132,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 +169,27 @@ 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
+      # Your credential resolver, for people's own MCP credentials (DEPLOYMENT.md, Credentials);
+      # unset by default. Set both in the shell that runs \`nylorun start\`.
+      NYLORUN_RESOLVER_URL: \${NYLORUN_RESOLVER_URL:-}
+      NYLORUN_RESOLVER_TOKEN: \${NYLORUN_RESOLVER_TOKEN:-}${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,12 +207,12 @@ 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
       # The Tenant the Runtime creates on its first start (later starts open it).
       NYLORUN_TENANT_NAME: \${NYLORUN_TENANT_NAME:?run nylorun start}
-      NYLORUN_DERIVED_PRINCIPALS: \${NYLORUN_DERIVED_PRINCIPALS:-project}
       # Model calls, remote MCP calls and deliveries go through the gateway, and vault writes
       # and token signing through its keys service: this container never reads a credential
       # or the vault key.
@@ -168,8 +237,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 : ""}${identity ? IDENTITY_RUNTIME_ENV : ""}
     extra_hosts:
       host.docker.internal: host-gateway # the Docker host, also on Linux Docker Engine
     volumes:
@@ -183,11 +262,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
@@ -211,12 +293,16 @@ services:
       # Browsers share cookies across ports of one host: a cookie per Tenant keeps the
       # sessions of two Studios on localhost apart.
       NYLORUN_STUDIO_SESSION_COOKIE: nylorun_studio_${name}
-      # Exact origins that may frame Studio (Babai Desktop); kept in .env.
+      # Exact origins that may frame Studio (none by default: embedding is opt-in); kept in .env.
       NYLORUN_STUDIO_FRAME_ANCESTORS: \${NYLORUN_STUDIO_FRAME_ANCESTORS:-}
       # Studio's anonymous usage analytics; empty when telemetry is off.
       NYLORUN_STUDIO_ANALYTICS_ID: \${NYLORUN_STUDIO_ANALYTICS_ID:-}
+      # Extra Host values Studio serves behind a sign-in proxy (studio.acme.dev),
+      # comma-separated; from the environment of nylorun start.
+      NYLORUN_STUDIO_ALLOWED_HOSTS: \${NYLORUN_STUDIO_ALLOWED_HOSTS:-}
     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 +311,135 @@ 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.
+ */
+/** The identity file (`<Host root>/identity.yaml`): the trusted issuers, read at boot. */
+const IDENTITY_RUNTIME_ENV = `
+      # Trusted issuers (<Host root>/identity.yaml): JWTs from the operator's identity provider.
+      NYLORUN_IDENTITY_FILE: /nylorun/identity.yaml`;
+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

@@ -1,8 +1,8 @@
 /**
- * Origins that may embed Studio by default: Babai Desktop's `nylorun` scheme on
- * macOS and Linux, and its WebView2 origin on Windows (Studio §8.9).
+ * Origins that may embed Studio by default: none. Embedding is opt-in: the operator lists
+ * the exact origins of the app that frames Studio (`--studio-embed-origin`, Studio §8.9).
  */
-export declare const DEFAULT_STUDIO_FRAME_ANCESTORS: readonly ["nylorun://localhost", "http://nylorun.localhost"];
+export declare const DEFAULT_STUDIO_FRAME_ANCESTORS: readonly string[];
 /**
  * Settings in `docker/.env` (mode 0600). Ports, the password and the gates token
  * persist; the Restate identity public key is derived from `restate-identity.pem`.
@@ -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;
@@ -36,18 +57,28 @@ export interface StackEnv {
     studioAnalyticsId: string;
     /** The Tenant's name, which the Runtime gives the Tenant it creates. */
     tenantName: string;
-    /**
-     * Derived principals the Runtime registers on its Tenant, comma-separated (persists);
-     * always includes `project`, the Project link's principal.
-     */
-    derivedPrincipals: string;
+    /** Present once `nylorun sandbox enable` ran for the Tenant (F7.2). */
+    sandboxes?: SandboxStackEnv;
 }
-export declare function renderEnvFile(env: StackEnv): string;
 /**
- * `NYLORUN_DERIVED_PRINCIPALS`: comma-separated principal ids, as the Runtime accepts them
- * (not `studio`), with `project` first so the Project link's key always works.
+ * 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 declare function parseDerivedPrincipals(raw: string, source: string): string[];
+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;
 /** Parse KEY=value lines; comments and blank lines are skipped. */
 export declare function parseEnvLines(text: string): Map<string, string>;
 /** The settings that persist across starts, from an existing .env. */
@@ -56,10 +87,15 @@ 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;