nylorun 0.6.0-beta → 0.8.0-beta

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # nylorun
 
+## 0.8.0-beta
+
+### Major Changes
+
+- b352feb: **File artifacts, message parts and capability links (protocol 6).** Upgrade these with the Runtime: they speak protocol 6, which this Runtime serves beside 4 and 5. See MIGRATION.md.
+
+  - **`@nylorun/runtime`: file artifacts.** A file is an artifact: an `af_` id, a name and numbered immutable versions, with rows in the new `artifacts` and `artifact_versions` tables (migration `0004_artifacts`) and bytes in the Object store (`BlobStore`). `POST /v1/artifacts?name=&sessionId=` uploads a file in one streamed request and `POST /v1/artifacts/{id}/versions` adds a version, within the Tenant's limits (`GET`/`PUT /v1/tenant/artifacts`: 100 MiB per file and 10 GiB in all by default); a body past either is `413 limit_exceeded`, refused mid-stream with nothing stored. `GET /v1/artifacts` lists them (by session), `GET /v1/artifacts/{id}` reads one with its versions, `GET /v1/artifacts/{id}/versions/{n|latest}/content` downloads through the Runtime with HTTP Range (`206`, `Content-Range`, `416`), and `DELETE /v1/artifacts/{id}` deletes it with its bytes. A session's artifacts go with it on a sessions reset, and appear in its history as `artifact.created`, `artifact.version.created` and `artifact.deleted` (new in the event catalog). A subject reaches only the artifacts of their own sessions.
+  - **`@nylorun/runtime`: capability links.** `POST /v1/artifacts/{id}/links` mints a short-lived path, `/v1/artifact-links/<token>`, that downloads one version (with Range) with no credential and no `Nylorun-Protocol`: an ES256 JWT (`typ: nylorun-artifact+jwt`) signed with the Tenant's signing key, at most 15 minutes, and dead once the artifact is deleted. The Host logs its path without the token.
+  - **Breaking (`@nylorun/core`, `@nylorun/runtime`): message `parts`.** A user message may carry `parts`: `text`, and `file` by `artifactId` (and `version`, else the latest, pinned when the message is accepted). Model-gate reads the file from the Object store: an image goes to the model as image input, a text file as text, and any other file fails the call (`invalid_request`). The record and the transcript hold only the reference. The gateway builds its `BlobStore` from `NYLORUN_OBJECT_STORE_*` (the Tenant's `fs` store without it). `PROTOCOL_VERSION` is 6; `HOST_PROTOCOL` is 4–6 and protocol 6 clients require the feature `artifacts`.
+  - **`@nylorun/runtime`: `save_artifact`.** A session with a sandbox gets the `nylorun.artifacts` capability, whose `save_artifact` tool saves a sandbox file (`path`) or text (`content`) as an artifact of the session, carrying the turn and tool call on its event.
+  - **Breaking (`@nylorun/runtime`): `MediaStore` is removed.** `MediaStore` and `localMedia` leave `@nylorun/runtime/node`, and `piModel` takes `files` (a resolver from an artifact reference to its bytes) instead of `media`; images are file artifacts. The image checks (`decodeImageBase64`, `validateImageBytes`, `IMAGE_MEDIA_TYPES`, `MAX_IMAGE_BYTES`) stay.
+  - **`@nylorun/agents`:** `client.artifacts` (`upload`, `uploadVersion`, `list`, `get`, `download` with a range, `link`, `delete`), also on `BrowserClient`, and `session.inputParts(parts)`. A request with a body of its own type keeps it.
+  - `@nylorun/admin`, `@nylorun/cli`, `nylorun`, `@nylorun/studio`: speak protocol 6.
+
+### Minor Changes
+
+- e58e6ec: **egress-gate: pod sandboxes reach only the hosts their spec allows (F7.2).** A new `egress` service runs in the gateway's process (`--service gates,keys,egress`) on `NYLORUN_EGRESS_LISTEN_PORT` (default 4200). It is a CONNECT proxy: each tunnel needs an egress token (`Proxy-Authorization`, Basic with the token as password or Bearer) for a live sandbox at its current host epoch, a host name (no IP literal) that the sandbox's `network.allow` names exactly or by `*.suffix`, port 443 or 80, and a name that resolves to a public address; the gate connects to that checked address and pipes bytes, with no TLS interception and no credential injection. Plain HTTP is answered `405`; a sandbox holds at most 64 tunnels; idle tunnels close after 5 minutes; refusals are logged, never emitted as events. Egress tokens (`typ: nylorun-egress+jwt`), minted with each host token at a pod's join, are accepted nowhere else; egress-gate also refuses a token of a sandbox that is deleted, lost or expired, or of a pod other than the one that joined. Sandbox spec resolution lets `pod` sandboxes allow `*.suffix` hosts within the Tenant's ceiling (virtual ones keep exact names). With sandboxes enabled, `nylorun` runs the gateway with `egress` and publishes it on `NYLORUN_SANDBOX_BIND` at `NYLORUN_SANDBOX_EGRESS_PORT`, next to the gates.
+- 186ec3f: **A local Tenant has an Object store: RustFS, behind the Runtime's new `BlobStore` seam.** `nylorun start` adds a `rustfs` container (RustFS 1.0.1, single node and single drive, pinned by digest) on the `nylorun-<tenant>-rustfs` volume, unpublished and without its console. Its secret key is generated once into `docker/.env` (`NYLORUN_OBJECT_STORE_SECRET_KEY`), and only the `runtime` and `gateway` containers receive the credential (`NYLORUN_OBJECT_STORE_ENDPOINT`, `_ACCESS_KEY`, `_SECRET_KEY`); the runtime creates the bucket at boot. The Runtime reaches the store through `BlobStore` (put with a streamed body and a size cap, get with a byte range, head, delete, list by prefix) with an `s3` adapter over the plain S3 API and an `fs` adapter, which a Runtime without `NYLORUN_OBJECT_STORE_ENDPOINT` (embedded, ephemeral, tests) uses under the Tenant directory's `blobs/`. Nothing stores files there yet; file artifacts build on it.
+- 3fd1cda: **The harness container, the network split, and Restate's UI closed by default (F6.2).** A local Tenant now runs agent turns, stdio MCP servers and workspaces in a `harness` container: the runtime image as `--service harness`, connected to the runtime's Harness API (`ws://runtime:4200/nylorun/harness/v1`, `NYLORUN_HARNESS=remote`) with `NYLORUN_HARNESS_TOKEN`, which `nylorun start` generates once and keeps in `.env`. The harness holds no other credential, mounts only the Tenant directory's `sandboxes/`, `plugin-data/`, `home/` and `tmp/` under `/harness`, publishes no port and is healthy once connected; `nylorun status` and `nylorun doctor` report it, and `nylorun logs harness` shows its log. `NYLORUN_HARNESS=in-process` in `.env` rolls back to turns in the runtime container (the harness service is then removed).
+
+  - Plugin roots: the Host root's `plugins/` directory is mounted read-only at its own path into the harness and runtime containers, so a stdio MCP server from a plugin under `~/.nylorun/tenants/<name>/plugins/` runs in the harness.
+  - Networks: `<project>-store` (internal) joins Postgres, s2-lite, Restate and RustFS to the runtime and the gateway only; `<project>-harness` joins the harness to the runtime and the gateway only; the default network keeps egress and the published ports.
+  - Restate's admin API and UI (unauthenticated) are no longer published. `nylorun start --restate-ui` (or `NYLORUN_RESTATE_UI=1`) publishes them on loopback for that start and prints the URL.
+
+- 678e085: **Pod sandboxes (F7.2, second part).** With `nylorun sandbox enable`, a sandbox resource of kind `pod` (`PUT /v1/sandboxes/{id}` with `kind: "pod"`, an `image`, `*.suffix` hosts, `storage` and `lifecycle.ttl`) is an agent-sandbox pod on the Tenant's cluster, created at once. The turns of the sessions attached to it run in the pod: the engine is copied from the Runtime image into the pod (the Runtime image now carries tini for it), waits until the pod's NetworkPolicy is in force, exchanges its join token for a host token at the Harness API listener (`POST /nylorun/harness/v1/host/join`, published for pods on the Docker host's address, with the gates), and serves its sandbox alone. New: `POST /v1/sandboxes/{id}/stop` and `/reset`; the Tenant's `limits.ttl`, `lifecycle.onExpiry`, `lifecycle.stopGrace` and `placement`; idle stop; lifecycle events `sandbox.running`, `.suspended`, `.expired`, `.relaunched`, `.lost`, `.reset` and `.failed`; error codes `placement_refused`, `sandbox_lost` and `sandbox_expired`; `cluster` in `GET /v1/tenant/sandbox`; Host feature `sandbox-pods` (additive, protocol unchanged). Without a cluster, kind `pod` is `409 sandbox_unavailable` (it was 400). Migration `0007_sandbox_pods` adds the pod lifecycle columns to `sandbox_resources`.
+- 926711b: **Sandboxes are a resource (F7.1, blueprint D39; Host feature `sandboxes`).** A sandbox has its own id, a kind, a spec and labels, and outlives the sessions attached to it. Additive: protocol 5 is unchanged.
+
+  - `PUT /v1/sandboxes/{id}` creates a sandbox or finds the one with that id (get-or-create in one call); `GET /v1/sandboxes/{id}`, `GET /v1/sandboxes?label=key=value` (repeatable), `GET /v1/sandboxes/{id}/events` and `DELETE /v1/sandboxes/{id}`. Ids are `/`-separated segments (`team-a/proj-42`), sent percent-encoded as one path segment. Only kind `virtual` runs; `pod` is refused with `sandbox_unavailable`. The spec is resolved against the Tenant's limits and fixed once the sandbox exists; labels can change.
+  - A session attaches with `sandbox: { id }` and shares the sandbox's `/workspace` with every other session attached to it. Turns are serial per sandbox: a second session's turn is refused with `409 sandbox_busy` while another runs. Deleting a session (a sessions reset) only detaches it. Deleting a sandbox is refused while a turn runs in it; afterwards an attached session's next turn is refused with `sandbox_unavailable` until a sandbox with that id exists again.
+  - Subject tokens carry an `sbx` claim: `POST /v1/tokens` takes `sandboxes`, exact ids or prefixes ending in `/*` (at most 16). A token reaches only the sandboxes they match, checked when a session attaches and at every turn start (`403 sandbox_not_granted`); any other sandbox is the 404 of a missing one. The new scope `sandboxes:write` lets a role create and delete the sandboxes its grants reach. Application keys reach every sandbox.
+  - The Tenant holds at most `limits.sandboxes` sandboxes (`PUT /v1/tenant/sandbox`, default 100); one more is `409 limit_exceeded`.
+  - Lifecycle events (`sandbox.created`, `sandbox.attached`, `sandbox.detached`, `sandbox.deleted`) go to the sandbox's own stream in the record, through the record module; the session's log records `sandbox.attached`. The sandbox stream is not relayed to S2.
+  - New error codes `sandbox_not_granted`, `sandbox_busy` and `sandbox_unavailable`; the session view gains `sandboxId` and `sandboxSource: "sandbox"`. Migration `0004_sandbox_resources` adds `sandbox_resources`, `nylorun_streams.sandbox_events` and the sessions' `sandbox_id` column.
+  - `@nylorun/agents`: `client.sandboxes` with `ensure(id, spec)`, `get`, `list({ labels })`, `delete`, `events`, and `forSession({ session, spec })`, which creates a sandbox for one session, opens the session on it, and deletes it with `release()`. It replaces sharing through another session (`sandbox: { session }` and the view's `sandboxOwnerId`, now deprecated). `client.tokens.create` takes `sandboxes`.
+  - `nylorun sandbox ls [--label key=value]... [--json]` and `nylorun sandbox rm <id>` list and delete the running local Tenant's sandboxes.
+
+- db045cd: **The sandboxes service and `nylorun sandbox enable` (F7.2, first part).** A new image, `ghcr.io/nylorun/sandboxes`, versioned with the Runtime, drives agent-sandbox v1.0.5 Sandboxes in one namespace per Tenant: `PUT`, `GET ?wait=` and `DELETE /v1/pods/{name}` with an operation id, `/ready` and `/v1/info`, behind a bearer token only the runtime container holds. `nylorun sandbox enable --context <name>` installs into that kubeconfig context only (the pinned controller when absent, the namespace `nylorun-sbx-<tenant>`, a ServiceAccount whose Role covers Sandbox lifecycle and join Secrets, no NetworkPolicy or exec rights), refuses a cluster whose NetworkPolicy it cannot prove enforced, records `<Host root>/sandboxes/cluster.json` and the token, and adds the `sandboxes` service to the Tenant; `nylorun sandbox disable` and `nylorun sandbox status` remove and report it. Sessions do not run in pods yet: that comes with the Harness API and egress-gate.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [b352feb]
+- Updated dependencies [6077272]
+- Updated dependencies [b6bf1f5]
+- Updated dependencies [8ed4ea6]
+- Updated dependencies [678e085]
+- Updated dependencies [926711b]
+  - @nylorun/core@0.12.0-beta
+
+## 0.7.0-beta
+
+### Minor Changes
+
+- 9af30d8: **The Studio proxy is removed, and Restate runs with its own memory defaults.** Each Tenant's Studio is at `http://localhost:<port>` again (`nylorun studio --tenant <name>` opens it signed in): its own session cookie already keeps it apart from other Studios, so the proxy only added a container and a second address. The 256 MiB RocksDB cap did not lower Restate's memory, so it is gone. The first command of this release removes the proxy that 0.6 started (`nylorun-proxy` and `~/.nylorun/proxy/`); `NYLORUN_PROXY_PORT`, `NYLORUN_PROXY_DISABLED`, `studio.proxyUrl` and Studio's `NYLORUN_STUDIO_PUBLIC_ORIGINS` are gone.
+
+### Patch Changes
+
+- Pin studio to the tested release.
+
 ## 0.6.0-beta
 
 ### Minor Changes

package/README.md

@@ -34,17 +34,23 @@ npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the Tenan
 ## Commands
 
 ```sh
-nylorun up|start [--tenant <name>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]
+nylorun up|start [--tenant <name>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset] [--restate-ui]
                                    # create (first run) and start the Tenant; link the project; print the URLs; open Studio signed in
-nylorun down|stop [--tenant <name> | --all]   # stop the containers (--all: every Tenant's, and the Studio proxy); keep volumes
+                                   # --restate-ui (or NYLORUN_RESTATE_UI=1): publish Restate's UI on loopback for this start
+nylorun down|stop [--tenant <name> | --all]   # stop the containers (--all: every Tenant's); keep volumes
 nylorun status [--tenant <name>] [--json]   # the Tenant, its Host root and id, services, endpoints, Runtime health
-nylorun logs [service] [--tenant <name>] [-f] [--tail <n>]   # postgres, restate, s2-lite, gateway, runtime, studio
+nylorun logs [service] [--tenant <name>] [-f] [--tail <n>]   # postgres, restate, s2-lite, rustfs, gateway, runtime, harness, studio, sandboxes
 nylorun studio [--tenant <name>] [--no-open]   # sign a browser in to Studio on the Tenant; starts it if needed
 nylorun reset [--tenant <name>] [--yes]        # delete the Tenant's volumes, Tenant directory and vault key; the next start creates it anew
 nylorun ls [--json]                # the Tenants on this machine, with their state, memory and URLs
 nylorun delete <tenant> --yes      # remove a Tenant: containers, volumes, Host root and vault key
+nylorun sandbox ls [--tenant <name>] [--label <key=value>]... [--json]   # the running Tenant's sandboxes
+nylorun sandbox rm <id> [--tenant <name>]   # delete a sandbox and its files
 nylorun doctor [--json]            # prerequisites and the Tenant's health
 nylorun telemetry [status|enable|disable]   # Studio's anonymous usage analytics
+nylorun sandbox enable --context <name> [--tenant <name>] [--host-address <ip>] [--bind-address <ip>] [--no-pull]
+nylorun sandbox disable [--tenant <name>] [--delete-namespace]
+nylorun sandbox status [--tenant <name>] [--json]   # pods on a Kubernetes context (see Sandboxes)
 ```
 
 `up` and `down` are the Docker Compose spellings of `start` and `stop`: `down`
@@ -82,29 +88,29 @@ projects and volumes.
 
 Tenants run side by side, each on its own ports, containers, network and
 volumes ([The containers](#the-containers)); a running Tenant uses about
-600–700 MB. Each Studio has its own address through the
-[Studio proxy](#the-studio-proxy), `http://<name>.localhost:4160`. `nylorun ls`
+1.2 GB. Each Studio is on its own port, `http://localhost:<port>`, with its own
+session cookie, so two Studios in one browser stay signed in;
+`nylorun studio --tenant <name>` opens any Tenant's Studio signed in. `nylorun ls`
 lists them with their state, the memory their containers use (`MEMORY`: the sum
 of `docker stats` over the containers labelled `dev.nylorun.tenant=<name>`, `-`
 when stopped; `memoryBytes` in `--json`, `null` when stopped or unknown), the
 Runtime's URL and Studio's:
 
 ```text
-TENANT   STATE    MEMORY  RUNTIME                STUDIO                         PROJECT
-api      running  652 MB  http://localhost:8790  http://api.localhost:4160      /Users/me/api
-default  stopped  -       http://localhost:8787  http://default.localhost:4160  -
+TENANT   STATE    MEMORY  RUNTIME                STUDIO                 PROJECT
+api      running  1.2 GB  http://localhost:8790  http://localhost:4162  /Users/me/api
+default  stopped  -       http://localhost:8787  http://localhost:4161  -
 ```
 
 When other Tenants are running, `start` says so after its summary, on stderr
 (without the size when Docker does not report it):
 
 ```text
-Also running: default, api (about 1.3 GB). "nylorun stop --all" stops them all.
+Also running: default, api (about 2.4 GB). "nylorun stop --all" stops them all.
 ```
 
-`nylorun stop --all` stops every running Tenant on this machine and the Studio
-proxy, keeping their volumes; it cannot be combined with `--tenant` (exit 2).
-`stop` of one Tenant leaves the proxy running.
+`nylorun stop --all` stops every running Tenant on this machine, keeping their
+volumes; it cannot be combined with `--tenant` (exit 2).
 
 A Tenant created by nylorun 0.5 keeps its data in volumes Compose named
 `<project>_postgres`, `<project>_restate`, `<project>_s2` and
@@ -157,77 +163,52 @@ The Runtime registers the derived principals of `NYLORUN_DERIVED_PRINCIPALS`
 `nylorun start` writes `compose.yaml` and `.env` (mode 0600) under
 `~/.nylorun/tenants/<name>/docker/` on every start; `.env` keeps the ports and
 secrets chosen on the first run. The services are `postgres`, `restate`,
-`s2-lite`, `gateway`, `runtime` and `studio`. Container, network and volume
+`s2-lite`, `rustfs`, `gateway`, `runtime`, `harness` and `studio`. Container, network and volume
 names are global on the Docker engine, so each carries the Tenant's Compose
 project, and each has the label `dev.nylorun.tenant: <name>`. For Tenant `shop`:
 
 | Thing | Name |
 | --- | --- |
-| Containers | `nylorun-shop-postgres`, `nylorun-shop-restate`, `nylorun-shop-s2-lite`, `nylorun-shop-gateway`, `nylorun-shop-runtime`, `nylorun-shop-studio` |
-| Network | `nylorun-shop` |
-| Volumes | `nylorun-shop-postgres`, `nylorun-shop-restate`, `nylorun-shop-s2-lite`, `nylorun-shop-workspaces` |
-
-Postgres initialises the Tenant's database with C collation. Restate's RocksDB
-memory is capped at 256 MiB (`RESTATE_ROCKSDB_TOTAL_MEMORY_SIZE`; Restate's
-default is 2 GiB), so several Tenants fit on a laptop: a Tenant uses about
-600–700 MB, down from about 1.3 GB. The Runtime and Studio images are pinned by
+| Containers | `nylorun-shop-postgres`, `nylorun-shop-restate`, `nylorun-shop-s2-lite`, `nylorun-shop-rustfs`, `nylorun-shop-gateway`, `nylorun-shop-runtime`, `nylorun-shop-harness`, `nylorun-shop-studio` |
+| Networks | `nylorun-shop` (egress, published ports), `nylorun-shop-store` (internal: the stores), `nylorun-shop-harness` (the harness, the runtime and the gateway) |
+| Volumes | `nylorun-shop-postgres`, `nylorun-shop-restate`, `nylorun-shop-s2-lite`, `nylorun-shop-rustfs`, `nylorun-shop-workspaces` |
+
+The `harness` container (the Runtime image as `--service harness`) runs agent
+turns, stdio MCP servers and workspaces, apart from the `runtime` container. It
+holds only the harness token (`NYLORUN_HARNESS_TOKEN` in `.env`), mounts only
+the Tenant directory's `sandboxes/`, `plugin-data/`, `home/` and `tmp/`, and the
+Host root's `plugins/` read-only at its own path: put a plugin whose stdio MCP
+server the agent runs under `~/.nylorun/tenants/<name>/plugins/` and load it from
+there. `NYLORUN_HARNESS=in-process` in `.env` rolls back to running them in the
+`runtime` container (no `harness` container); `nylorun status` shows which.
+
+Postgres initialises the Tenant's database with C collation. Restate runs with
+its own defaults. A running Tenant uses about 1.2 GB, most of it Restate; stop
+the Tenants you are not using (`nylorun stop`, or `nylorun stop --all`). The Runtime and Studio images are pinned by
 this release (`package.json` `nylorun.runtime` and `nylorun.studio`);
 `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them (local builds,
 CI). Ports publish on loopback only: the Runtime on `8787`, its operator
-listener (Admin API) on `8788`, Studio on `4161` and the Restate UI on `9070`,
-or free ports chosen on the Tenant's first start, avoiding the ports other
-Tenants and the Studio proxy keep, and kept in its `.env`.
-
-`start`, `ls` and `nylorun studio` give Studio as `http://<name>.localhost:4160`,
-its address through the Studio proxy (below); `status` adds Studio's own
-`http://localhost:<port>` (`--json` has both: `studio.url` is Studio's own port,
-which an embedding app frames, and `studio.proxyUrl` the proxy's). Studio has no
+listener (Admin API) on `8788` and Studio on `4161`, or free ports chosen on the
+Tenant's first start, avoiding the ports other Tenants keep, and kept in its
+`.env`. Restate's UI and admin API (unauthenticated) are not published; `nylorun
+start --restate-ui` (or `NYLORUN_RESTATE_UI=1`) publishes them for that start on
+`9070` (or the port kept in `.env`), and the next start without it closes them.
+
+`start`, `status`, `ls` and `nylorun studio` give Studio as
+`http://localhost:<port>` (`studio.url` in `status --json`). Studio has no
 password: in a terminal (not in CI, and not with `--no-open`), `start` asks the
 Studio container for a single-use login token with the admin key (`POST
-/_studio/login-tokens`, through the proxy; on Studio's own port, saying so,
-when the proxy does not answer) and opens `…/login?token=…` on the Tenant's
-page in the browser. That sets a session cookie for 30 days, which survives
-Studio restarts, so the printed URL keeps working in that browser. The token
-itself is never printed unless no browser starts. Otherwise `start` says to run
-`nylorun studio`, which signs a browser in the same way; `nylorun studio
+/_studio/login-tokens`) and opens `http://localhost:<port>/login?token=…` on the
+Tenant's page in the browser. That sets a session cookie for 30 days, which
+survives Studio restarts, so the printed URL keeps working in that browser. The
+token itself is never printed unless no browser starts. Otherwise `start` says
+to run `nylorun studio`, which signs a browser in the same way; `nylorun studio
 --no-open` prints the login URL (it works once, for two minutes) instead.
 
-Each Tenant's Studio sets its own session cookie, `nylorun_studio_<name>`
-(`NYLORUN_STUDIO_SESSION_COOKIE`).
-
-### The Studio proxy
-
-One small Caddy container per machine (`nylorun-proxy`, Compose project
-`nylorun-proxy`, label `dev.nylorun.proxy: "true"`) gives every Tenant's Studio
-the address `http://<name>.localhost:<port>`. Browsers keep cookies per host,
-not per port, so separate hosts keep the Studios' sessions apart. The proxy is
-for browsers only: programs keep using the Runtime's `http://localhost:<port>`.
-It holds no Tenant data; its files are in `~/.nylorun/proxy/` (`compose.yaml`,
-`Caddyfile`, and `.env` with `NYLORUN_PROXY_PORT`, 4160 or a free port chosen
-on its first start and kept; Caddy's own state is tmpfs). Its image is pinned
-by this release (`caddy:2.11.6`).
-
-- Caddy listens on port 80 in the container, published at `NYLORUN_PROXY_PORT`
-  on `127.0.0.1` and `[::1]` (macOS resolves `*.localhost` to `::1` only); when
-  Docker refuses `::1` (IPv6 off), it publishes on `127.0.0.1` alone and says
-  so once.
-- It routes every Tenant under `~/.nylorun/tenants/`: it joins each Tenant's
-  network and reaches `<project>-studio:3000`, passing the browser's `Host`
-  through, which Studio checks. A stopped Tenant answers 502 naming
-  `nylorun start --tenant <name>`; an unknown host 404 naming `nylorun ls`.
-- `start` rewrites its files, brings it up (only when Studio starts: not with
-  `--no-studio`), joins every Tenant's network and reloads Caddy; Studio learns
-  its proxy origin from `NYLORUN_STUDIO_PUBLIC_ORIGINS`, written to the
-  Tenant's `.env` on every start. A proxy that does not come up never fails
-  `start`: it warns once and prints Studio's own URL.
-- `reset` and `delete` detach it from the Tenant's network first; `delete`
-  removes the Tenant's route. `stop --all` stops it.
-- `NYLORUN_PROXY_DISABLED=1` turns it off: Studio is `http://localhost:<port>`.
-  A Tenant under `NYLORUN_HOME` or `NYLORUN_COMPOSE_PROJECT` (the repository's
-  smokes) does not use it either.
-
-`nylorun doctor` reports it on a `proxy` row: running (on which loopbacks and
-port), stopped, not created yet, or disabled.
+Browsers share cookies across the ports of one host, so each Tenant's Studio
+sets its own session cookie, `nylorun_studio_<name>`
+(`NYLORUN_STUDIO_SESSION_COOKIE`): signing in to one Studio does not sign you
+out of another.
 
 ### Embedding Studio in a desktop app
 
@@ -269,6 +250,29 @@ default names one (`PUT /v1/tenant/sandbox`). A local Tenant runs them on the
 Runtime's **virtual** backend: an emulated shell in the Runtime process, with no
 extra containers. It is not a VM or container boundary.
 
+A sandbox can also be a resource with its own id (`PUT /v1/sandboxes/{id}`,
+`client.sandboxes` in `@nylorun/agents`) that sessions attach to and that
+outlives them. `nylorun sandbox ls` lists the running Tenant's sandboxes with
+their state, attached sessions and labels; `nylorun sandbox rm <id>` deletes one
+and its files (refused while a turn runs in it). Neither starts a stopped Tenant
+(exit 3).
+
+### Pods on a cluster (preview)
+
+`nylorun sandbox enable --context <name>` prepares a Kubernetes context for the
+Tenant's sandboxes as pods ([agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox)
+v1.0.5): Docker Desktop's cluster (`--context docker-desktop`) or kind. It only
+touches the context you name. It installs the pinned agent-sandbox controller
+when the cluster has none (and refuses another version), creates the namespace
+`nylorun-sbx-<tenant>` with a ServiceAccount limited to Sandbox lifecycle, proves
+with a probe that the cluster enforces NetworkPolicy (and refuses it otherwise),
+lets pods reach only three ports on the Docker host, and adds the `sandboxes`
+service to the Tenant: the one container holding the cluster credentials
+(`<Host root>/sandboxes/`). On kind under Linux, pass `--host-address 172.17.0.1`.
+`nylorun sandbox disable` removes the service (`--delete-namespace` also deletes
+the namespace and every sandbox in it). Sessions keep using the virtual backend
+in this release.
+
 ## Host root
 
 The **Host root** is `~/.nylorun/tenants/<name>/`, or `NYLORUN_HOME`. It is
@@ -291,7 +295,7 @@ containers, volumes and Host root: the vault key (KEK) and all its data go with
 | 0 | Success |
 | 1 | Generic failure, including a missing Docker or Compose v2 |
 | 2 | Usage error (including no Tenant selected, or `delete` without `--yes`), or a removed or moved command |
-| 3 | `status`: the Runtime is not answering; `stop`/`logs`: no Tenant yet; `delete`: no such Tenant; `start`: a Tenant created by nylorun 0.5 (reset it) |
+| 3 | `status`: the Runtime is not answering; `sandbox`: the Tenant is not running; `stop`/`logs`: no Tenant yet; `delete`: no such Tenant; `start`: a Tenant created by nylorun 0.5 (reset it) |
 | 4 | The Runtime port is held by another Host |
 | 5 | `up`/`start`/`studio`: this nylorun pins a Runtime older than the one that last ran the Tenant; update nylorun, or `start --allow-downgrade` |
 | 7 | The containers, the Tenant or Studio did not become ready (an unavailable Tenant's cause is printed) |
@@ -308,7 +312,7 @@ containers, volumes and Host root: the vault key (KEK) and all its data go with
 | Port conflict | Change `NYLORUN_PORT` / `NYLORUN_STUDIO_PORT` in `~/.nylorun/tenants/<name>/docker/.env` |
 | Logs | `nylorun logs runtime -f` |
 | Studio login expired | `nylorun studio` |
-| `http://<name>.localhost:<port>` does not answer | `nylorun doctor` (the `proxy` row); `nylorun start` brings the proxy up; Studio's own port is in `nylorun status` |
+| Which Studio is which | `nylorun ls` lists each Tenant's Studio URL; `nylorun studio --tenant <name>` opens one signed in |
 | `Tenant … was created by nylorun 0.5` (exit 3) | `nylorun reset --tenant <name>` (its data starts fresh) |
 
 See [MIGRATION.md](../MIGRATION.md).

package/dist/cli.js

@@ -2,11 +2,12 @@
 import "./baseline.js";
 import { baselineEnv } from "./baseline.js";
 import { CliError } from "./errors.js";
-import { isStackCommand, stackCommand, stackUsage, studioCommand, } from "./stack/index.js";
-const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|ls|delete|doctor|telemetry>
+import { isStackCommand, sandboxCommand, sandboxUsage, stackCommand, stackUsage, studioCommand, } from "./stack/index.js";
+const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|ls|delete|sandbox|doctor|telemetry>
 
 Local Tenants (Docker Compose), one per project:
 ${stackUsage}
+${sandboxUsage}
   doctor [--json]                     check Node, Docker and Compose v2, and the Tenant's health
   telemetry [status|enable|disable]   Studio's anonymous usage analytics (on unless disabled,
                                       NYLORUN_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 or CI)
@@ -45,6 +46,10 @@ async function main() {
         process.exitCode = await studioCommand(args, baselineEnv());
         return;
     }
+    if (command === "sandbox") {
+        process.exitCode = await sandboxCommand(args, baselineEnv());
+        return;
+    }
     if (isStackCommand(command)) {
         process.exitCode = await stackCommand(command, args, baselineEnv());
         return;

package/dist/doctor.d.ts

@@ -1,4 +1,4 @@
-import { type Check, type ProxyStatus, type StackDeps, type StackStatus } from "./stack/index.js";
+import { type Check, type StackDeps, type StackStatus } from "./stack/index.js";
 export interface StackDoctorReport {
     node: {
         version: string;
@@ -6,11 +6,9 @@ export interface StackDoctorReport {
     };
     docker: Check;
     compose?: Check;
-    tenant?: Pick<StackStatus, "name" | "project" | "home" | "state" | "runtime" | "tenant" | "studio" | "gateway">;
+    tenant?: Pick<StackStatus, "name" | "project" | "home" | "state" | "runtime" | "tenant" | "studio" | "gateway" | "harness">;
     /** Why no Tenant was checked: none is selected here (a project without a link). */
     noTenant?: string;
-    /** The machine's Studio proxy (`http://<tenant>.localhost:<port>`); never a failure. */
-    proxy?: ProxyStatus;
 }
 /**
  * `nylorun doctor`: check the prerequisites of a local Tenant (Node 24+,

package/dist/doctor.js

@@ -1,5 +1,5 @@
 import { CliError } from "./errors.js";
-import { checkDocker, defaultStackDeps, readProxyReport, readStackStatus, } from "./stack/index.js";
+import { checkDocker, defaultStackDeps, readStackStatus, } from "./stack/index.js";
 /** Oldest Node nylorun and the developer's application run on. */
 const MIN_NODE_MAJOR = 24;
 /**
@@ -29,6 +29,7 @@ export async function doctorStack(options) {
                 ...(status.tenant ? { tenant: status.tenant } : {}),
                 studio: status.studio,
                 gateway: status.gateway,
+                harness: status.harness,
             };
         }
         catch (error) {
@@ -36,11 +37,11 @@ export async function doctorStack(options) {
                 throw error;
             report.noTenant = error.message;
         }
-        report.proxy = await readProxyReport(deps);
     }
     const broken = report.tenant?.state === "running" &&
         (!report.tenant.runtime.healthy ||
             !report.tenant.gateway.healthy ||
+            (report.tenant.harness.mode === "remote" && !report.tenant.harness.healthy) ||
             report.tenant.tenant?.cause !== undefined);
     const failed = !nodeOk || !checks.docker.ok || checks.compose?.ok === false || broken;
     if (options.json) {
@@ -89,6 +90,14 @@ export async function doctorStack(options) {
                     ? `✓ ${local.gateway.state} · combined packing (runtime: core,loop; gateway: gates)`
                     : `✗ ${local.gateway.state}: model calls fail; see nylorun logs gateway`,
             ]);
+            rows.push([
+                "harness",
+                local.harness.mode === "in-process"
+                    ? "- in-process (NYLORUN_HARNESS=in-process in .env)"
+                    : local.harness.healthy
+                        ? `✓ ${local.harness.state} · remote (agent turns, MCP servers, workspaces)`
+                        : `✗ ${local.harness.state}: turns do not run; see nylorun logs harness`,
+            ]);
             if (local.tenant)
                 rows.push([
                     "tenant id",
@@ -96,25 +105,9 @@ export async function doctorStack(options) {
                         ? `✓ ${local.tenant.id ?? "?"} open`
                         : `✗ ${local.tenant.id ?? "?"} unavailable${local.tenant.cause ? `: ${local.tenant.cause.code}: ${local.tenant.cause.repair}` : " (opening)"}`,
                 ]);
-            rows.push(["studio", `${local.studio.proxyUrl ?? local.studio.url ?? "?"} · ${local.studio.state}`]);
+            rows.push(["studio", `${local.studio.url ?? "?"} · ${local.studio.state}`]);
         }
     }
-    const proxy = report.proxy;
-    if (proxy) {
-        const on = proxy.port
-            ? `127.0.0.1:${proxy.port}${proxy.ipv6 ? ` and [::1]:${proxy.port}` : ""}`
-            : "";
-        rows.push([
-            "proxy",
-            proxy.state === "running"
-                ? `✓ running on ${on} (http://<tenant>.localhost:${proxy.port ?? "?"})`
-                : proxy.state === "disabled"
-                    ? "- disabled (NYLORUN_PROXY_DISABLED): Studio is on each Tenant's own port"
-                    : proxy.state === "stopped"
-                        ? `- stopped${on ? ` (${on})` : ""}: nylorun start starts it`
-                        : "- not created yet: nylorun start creates it",
-        ]);
-    }
     const width = Math.max(...rows.map(([key]) => key.length)) + 2;
     for (const [key, value] of rows)
         log(`  ${key.padEnd(width)}${value}`);

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

@@ -0,0 +1,47 @@
+/**
+ * `<Host root>/sandboxes/`: what the sandboxes service mounts read-only. `cluster.json`
+ * records the cluster `nylorun sandbox enable` installed into; `token` is the
+ * ServiceAccount token (0600). Only the sandboxes container reads them: the runtime
+ * container sees an empty mount there.
+ */
+export interface ClusterFile {
+    context: string;
+    /** The API server URL in the kubeconfig. */
+    server: string;
+    /** host:port the sandboxes container dials. */
+    dial: string;
+    /** The name the API server's certificate is verified against. */
+    tlsServerName: string;
+    /** The cluster CA, base64 PEM. */
+    caData: string;
+    namespace: string;
+    controllerVersion: string;
+    hostAddress: string;
+    bindAddress: string;
+    ports: {
+        harness: number;
+        gates: number;
+        egress: number;
+    };
+    networkPolicy: {
+        enforced: boolean;
+        probedAt: string;
+    };
+    enabledAt: string;
+}
+export declare function sandboxesDir(root: string): string;
+export declare function clusterFilePath(root: string): string;
+/** Sandboxes are enabled for the Tenant under `root`. */
+export declare function sandboxesEnabled(root: string): boolean;
+export declare function readClusterFile(root: string): Promise<ClusterFile | undefined>;
+export declare function writeClusterFiles(root: string, cluster: ClusterFile, token: string): Promise<void>;
+export declare function removeClusterFiles(root: string): Promise<void>;
+/**
+ * How the sandboxes container reaches the API server. One on this machine's loopback
+ * (Docker Desktop's `https://127.0.0.1:<port>`) is dialled at `host.docker.internal:<port>`
+ * while the certificate is still verified against the kubeconfig's host (Experiment 2, Q3).
+ */
+export declare function apiRoute(server: string): {
+    dial: string;
+    tlsServerName: string;
+};

package/dist/sandbox/cluster-file.js

@@ -0,0 +1,55 @@
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export function sandboxesDir(root) {
+    return join(root, "sandboxes");
+}
+export function clusterFilePath(root) {
+    return join(sandboxesDir(root), "cluster.json");
+}
+/** Sandboxes are enabled for the Tenant under `root`. */
+export function sandboxesEnabled(root) {
+    return existsSync(clusterFilePath(root));
+}
+export async function readClusterFile(root) {
+    try {
+        return JSON.parse(await readFile(clusterFilePath(root), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeFileMode(path, text, mode) {
+    const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+    await writeFile(temporary, text, { mode });
+    await rename(temporary, path);
+    await chmod(path, mode);
+}
+export async function writeClusterFiles(root, cluster, token) {
+    const dir = sandboxesDir(root);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+    await writeFileMode(join(dir, "token"), token, 0o600);
+    await writeFileMode(clusterFilePath(root), `${JSON.stringify(cluster, null, 2)}\n`, 0o600);
+}
+export async function removeClusterFiles(root) {
+    await rm(sandboxesDir(root), { recursive: true, force: true });
+}
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+/**
+ * How the sandboxes container reaches the API server. One on this machine's loopback
+ * (Docker Desktop's `https://127.0.0.1:<port>`) is dialled at `host.docker.internal:<port>`
+ * while the certificate is still verified against the kubeconfig's host (Experiment 2, Q3).
+ */
+export function apiRoute(server) {
+    const url = new URL(server);
+    if (url.protocol !== "https:")
+        throw new Error(`the API server ${server} is not https`);
+    const port = url.port || "443";
+    const host = url.hostname;
+    const bare = host.replace(/^\[|\]$/g, "");
+    if (LOOPBACK.has(host) || LOOPBACK.has(bare))
+        return { dial: `host.docker.internal:${port}`, tlsServerName: bare };
+    return { dial: `${host}:${port}`, tlsServerName: bare };
+}

package/dist/sandbox/commands.d.ts

@@ -0,0 +1,41 @@
+import { type StackDeps } from "../stack/commands.js";
+import type { FetchLike } from "../stack/studio-login.js";
+import { type ClusterFile } from "./cluster-file.js";
+import { type KubectlRunner } from "./kubectl.js";
+export declare const sandboxUsage = "  sandbox enable --context <name> [--tenant <name>] [--host-address <ip>] [--bind-address <ip>] [--no-pull]\n                                      run the Tenant's sandboxes as pods on that kubeconfig context (agent-sandbox v1.0.5)\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 {
+    stack: StackDeps;
+    kubectl: KubectlRunner;
+    /** Fetches the controller manifest; defaults to the stack's fetch. */
+    fetch?: FetchLike;
+    /** Poll interval and NetworkPolicy wait, for tests. */
+    pollMs?: number;
+    policyTimeoutMs?: number;
+}
+export interface InstallResult {
+    cluster: ClusterFile;
+    /** The ServiceAccount token. */
+    token: string;
+    /** Images the pre-pull could not pull. */
+    notPulled: string[];
+}
+/**
+ * Steps 2–8 of `enable` against one context: controller, namespace and RBAC, NetworkPolicy
+ * probe, the namespace's policy, pre-pull. Returns what cluster.json records.
+ */
+export declare function installCluster(deps: SandboxDeps, input: {
+    context: string;
+    tenant: string;
+    hostAddress?: string;
+    bindAddress?: string;
+    prePull: readonly string[];
+    ports: {
+        harness: number;
+        gates: number;
+        egress: number;
+    };
+}): Promise<InstallResult>;
+/** `nylorun sandbox <enable|disable|status>`. */
+export declare function runSandboxCommand(args: readonly string[], deps: SandboxDeps): Promise<number>;