# Compatibility (/docs/compatibility)



<Callout title="Pre-1.0: expect breaking changes" type="warn">
  Nylorun is in beta. APIs, specs, and on-disk formats change. Upgrade packages
  as a family and read the breaking changes below.
</Callout>

| Package or image                               | Version        |
| ---------------------------------------------- | -------------- |
| `nylorun`                                      | `0.32.0-beta`  |
| `@nylorun/cli` (nylorun under another name)    | `0.17.51-beta` |
| `@nylorun/create-agent`                        | `0.16.53-beta` |
| `@nylorun/agents`                              | `0.42.0-beta`  |
| `@nylorun/admin`                               | `0.21.0-beta`  |
| `@nylorun/core`                                | `0.50.0-beta`  |
| `@nylorun/harness`                             | `0.37.1-beta`  |
| `@nylorun/runtime` / `ghcr.io/nylorun/runtime` | `0.56.0-beta`  |
| `ghcr.io/nylorun/studio`                       | `0.38.0-beta`  |

Studio ships only as the image pinned by `nylorun`. Protocol 18: the Runtime
accepts protocol 16, 17, and 18 (a protocol 16 client's messages default to
`delivery: "reject"`, and a protocol 16 or 17 client reads usage without the
fields 18 added) and answers an older client `426`, naming the protocol it
needs. The SDKs send 18 and need the Host feature `usage-by-kind`, so they need
Runtime 0.29 or later; older SDKs keep working against this Runtime. Agent
manifest schema 8 only (authoring: manifests written as files, formats `agent-folder/1`,
`agent-folder/2` and `agent-folder/3`, and the deprecated three-file format's harness manifest 1 and runtime
manifest 1). Harness API 5 only. Agent manifest schema 8 and Harness API 5
gained fields without a new version; their JSON Schemas are published at new
ids, `/schemas/agent-manifest/v8.5.json`, `/schemas/harness-api/v5.8.json`,
`/schemas/harness-manifest/v1.5.json`, `/schemas/runtime-manifest/v1.2.json`,
`/schemas/agent-folder/v1/agent-md.5.json`, and
`/schemas/agent-folder/v1/runtime.2.json`, and the earlier ids stay served.
[A2A profile v2](/docs/a2a/profile/v2) needs this Runtime: the Host features
`a2a-profile-v2` and `turns`.

These versions are the documented release. `docs-site/lib/documented-release.json`
is the pin used by the OpenAPI and JSON Schema sync scripts.

## Upgrading [#upgrading]

1. Upgrade every Nylorun package in your project together.
2. Read the breaking changes for each release you skip.
3. Run `npm run check`.
4. Restart the Tenant with `npx nylorun start` and check `npx nylorun status`.
5. Start `npm run dev`, then run one session in Studio.

Clients negotiate protocol and features through `/health`. An incompatible
Runtime fails with `IncompatibleRuntimeError` before any authenticated work.
An older SDK works against a newer Runtime, not the reverse: restart the Tenant
on the new release before you deploy new SDKs.

### From `nylorun` 0.16 to 0.19 [#from-nylorun-016-to-019]

Upgrading from `nylorun` 0.16 or 0.17 (protocol 16 or 17), or from 0.18 or 0.19
(protocol 18), to this release deletes nothing.

* Upgrade `nylorun` and restart the Tenant first. Its migrations run at the
  first start (see [Docker Compose → Upgrades](/docs/deploy/vm#upgrades));
  keys, agent manifests, Agents, sessions, and settings carry over.
* Then upgrade `@nylorun/agents` and `@nylorun/admin`. `@nylorun/agents` 0.25
  and `@nylorun/admin` 0.19.1 and later send protocol 18: against a Tenant
  last started by `nylorun` 0.16 or 0.17, `@nylorun/agents` 0.28 throws
  `IncompatibleRuntimeError` at its first request, and `@nylorun/admin`
  throws `incompatible_host`.
* From `nylorun` 0.19, an agent manifest with ten or more `instructions/*.md`
  files compiles to a different manifest, since they now sort naturally
  (`2-style.md` before `10-tone.md`): its next `nylorun apply` saves a new
  version, and the Agents that track the manifest move to it.
* The three-file format (`agent.manifest.json`) and `secrets` in a `SKILL.md`
  are deprecated and still read, with a warning. `npx nylorun migrate folder <dir>`
  writes the agent manifest, with its skills' secrets in `AGENT.md`. See
  [Agent manifests](/docs/build/agent-manifests#three-files).

### From protocol 14 [#from-protocol-14]

Upgrading from `nylorun` 0.15 (protocol 14) to this release is one hop, but it
holds two fresh starts: protocol 15 for sessions, and protocol 16 for agents,
Environments, and sessions.

* Upgrade the Runtime, `@nylorun/agents`, `@nylorun/admin`, Studio, `nylorun`,
  and any custom harness image together. The Runtime speaks protocol 16, 17,
  and 18.
* Saved agents and environment manifests are gone. Write agent manifests v8
  (`npx nylorun migrate v8 <agent.json> --runtime <environment-manifest.json>`,
  then `npx nylorun apply <dir>`, or `client.agentManifests.save({ agent, runtime })`),
  make Agents from them, and write their secrets.
* Every open session is closed: its history stays readable, and a new message
  is `409 session_closed`. Open new sessions on Agents.
* Rename the identity file's `environments:` and `environments:write` to
  `agents:` and `agents:write` before the first start. An issuer without
  `agents` reaches no Agent.
* If a tool policy rule names a tool as `server__tool`, put the policy again
  with `server` and `tool`.
* Keys, the model, Tenant settings, budgets (scope `agent` becomes `manifest`,
  keyed by the manifest's name), and artifacts other than disk versions carry
  over.

<Callout title="Migration 0032 deletes every Environment" type="warn">
  The upgrade deletes every Environment with its pod's state, its disk, its
  disk versions, and its secrets. Before upgrading, with the old release,
  export what you need:

  ```sh
  npx nylorun environments snapshot <id>
  npx nylorun environments versions <id>
  npx nylorun artifacts zip <artifactId> --version <n> --output <id>.zip
  npx nylorun environments secrets list <id>
  npx nylorun environments manifests get <name>
  ```

  Secret values cannot be exported: have them at hand. Keep each agent's v7
  manifest JSON and each environment manifest's JSON for `nylorun migrate v8`.
  On a cluster, delete the dropped pods after the upgrade. The steps are on
  [Docker Compose → Upgrades](/docs/deploy/vm#upgrades).
</Callout>

## Breaking changes [#breaking-changes]

| Change                                                                                                                                                           | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Telemetry for operators, the Tenant's audit, and event layers (`nylorun` 0.32, Runtime 0.56, `@nylorun/agents` 0.42, `@nylorun/admin` 0.21)                      | Additive, with two variables deprecated. Every runtime and gateway process serves Prometheus metrics on `/metrics`, port `9464`, and with an OTLP endpoint pushes them and exports live spans; see [Monitor](/docs/deploy/monitor). **Content on spans is one switch, `OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT`** (`NO_CONTENT` or `SPAN_ONLY`): `NYLORUN_TRACE_CONTENT` and `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` still work for this release when it is unset, with a `trace_content_deprecated` warning, and there is no per-kind setting any more. Content is recorded as structured OTLP values, not JSON strings, and `execute_tool` spans gain `gen_ai.tool.call.arguments`. **`service.name` defaults to `nylorun-runtime`** (it was `nylorun`) and `nylorun-gateway`; `OTEL_SERVICE_NAME` still wins. The SDKs, the CLI and Studio send a `Nylorun-Client` header: a proxy with a CORS allow-list for a browser app must allow it. The Tenant's audit is `GET /v1/tenant/audit` (`admin.tenant.audit()`, Host feature `tenant-audit`); each event type's layer is `eventLayer()` in `@nylorun/agents`. See [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Runtime 0.48 to 0.55 (`nylorun` 0.29.6 to 0.31.11)                                                                                                               | Additive. Not every one is on these pages yet; among them: A2A `metadata.delivery: "steer"` (Runtime 0.48); a model call's `attempts` and `retries` on `message.assistant` and `model.failed` (0.50); an Agent's triggers over the API, `PUT /v1/agents/{agentId}/triggers/{triggerId}` (Host feature `api-triggers`, 0.52); the Runtime's Helm chart and pod Agents as computers on Agent Substrate (0.53, 0.54), with model roles (`roles` in `AGENT.md`, Host feature `model-roles`); an Agent's compaction threshold (`loop.compaction`) and a message's `context` (Host feature `message-context`, 0.55). Each release's changes are in the [Runtime changelog](https://github.com/nylorun/agents/blob/main/runtime/server/CHANGELOG.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Sandbox settings as stored and in force, `removeTools` by a plugin tool's own name, and A2A queued tasks (`nylorun` 0.29.5, Runtime 0.47, `@nylorun/admin` 0.20) | **Breaking for the Management API.** `GET` and `PUT /v1/tenant/sandbox` (`admin.settings.sandbox`) answer `config` as the Tenant set it, with no defaults, in the shape `PUT` takes, so `put(get().config)` changes nothing; the settings in force, with every default filled in and sizes in MiB, are now `effective`, which is what `config` was. Read limits from `effective` (`effective.limits.resources.memoryMiB`) and build a `PUT` body from `config`. Both carry `engine.images`. `nylorun tenant settings sandbox put` takes what `get` printed. Additive: a message's `removeTools` turns a [Runtime plugin's](/docs/build/agent-manifests#the-runtimes-plugins) tool off by its own name (`memory`) as well as `nylorun__memory`, and `nylorun check --explain` lists the names the model reads. Fixed: an A2A `SendMessage` with `returnImmediately` to a busy context answers `TASK_STATE_SUBMITTED`, and `CancelTask` on a queued task answers `TASK_STATE_CANCELED`, where both could answer `TaskNotFoundError`. See [Kubernetes](/docs/deploy/kubernetes) and [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| An agent sees the files it makes (`nylorun` 0.29.2, Runtime 0.46, core 0.40)                                                                                     | Additive, with one behaviour change. The sandbox's `read` of an image, a PDF or another file the turn's model reads as media returns the file itself to the model; **`read` of any other binary file fails `sandbox.binary_file`** where it answered decoded bytes. A model call carries at most 6 such files. The Harness API gains `audience: "model"` on `artifact.write` (schema 5.5). `read`'s new description changes every sandbox agent's prompt prefix once, so its first call after the upgrade misses the prompt cache. See [Files the agent makes](/docs/run/files#files-the-agent-makes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Pods on Agent Substrate, a preview (`nylorun` 0.29, Runtime 0.45, core 0.39)                                                                                     | Additive; nothing changes unless you choose it. `nylorun local sandbox enable --context <name> --backend substrate` runs the Tenant's pods as Agent Substrate v1.0 actors instead of agent-sandbox Sandboxes, on Kubernetes 1.37 with Substrate installed; agent-sandbox stays the default. `GET /v1/tenant/sandbox`'s `cluster` gains `backend` (`agent-sandbox` or `substrate`) and, on Agent Substrate, `atespace`; `nylorun doctor sandbox` prints a `pods` line, and Studio's Compute tab names the backend. Shell credentials are not on Agent Substrate yet. Later releases change only the preview: Runtime 0.46 and 0.46.1 make wakes faster (the edge pinned in each actor's `/etc/hosts`, and the engine redialing at once after a restore); 0.46.2 recovers a crashed actor from its last suspend and makes one resume per wake; 0.47 records a crashed sandbox at once as `agent.failed`, saying what the Agent lost. See [Agent Substrate](/docs/deploy/substrate).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Queued messages never wait for good (`nylorun` 0.27.2, Runtime 0.44)                                                                                             | Additive, with one behaviour change (Host feature `queue-recovery`). When an Agent refuses a turn's start for queued messages, the Runtime tries again; past the new Runtime limit `queuedStartMs` (15 minutes) they fail with the new event `queue.failed`. **A2A `CancelTask` on a queued task takes it out of the queue and answers `TASK_STATE_CANCELED`** (`queue.cancelled`), where it answered `TaskNotCancelableError`; a queued task that fails is `TASK_STATE_FAILED`. From `nylorun` 0.27.4 (Runtime 0.44.2), an agent that keeps a plan and has made 8 tool calls since it last moved it is reminded of its open step. See [Messages while a turn runs](/docs/run/sessions#messages-while-a-turn-runs).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Steer a running turn (`nylorun` 0.27.1, Runtime 0.43)                                                                                                            | Additive. A message takes `delivery: "steer"` (Host feature `steer`): a busy session's running turn reads it before its next step. The queued answer and `message.queued` carry `delivery`, and `queue.taken` may carry `step`. The Harness API gains the effect kind `inputs` (schema 5.4); a harness that never asks for it is unchanged. An older Runtime refuses `steer` with `400`. See [Steer a running turn](/docs/run/sessions#steer-a-running-turn).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| The Runtime's features as plugins (`nylorun` 0.27, Runtime 0.42)                                                                                                 | Additive. `format: agent-folder/3` declares the Runtime's features as [its plugins](/docs/build/agent-manifests#the-runtimes-plugins), by name under `plugins:`, and turns one of their tools off under `mcpServers.nylorun.tools`; it refuses `memory`, `loop`, `runtime.selfWake` and `engine.sandbox`, `artifacts`, `triggers` and `instructions`. The model reads their tools as `nylorun__<tool>`, with the Runtime's text under `# Server nylorun` and the plugins' skills in the catalog; each call's effect, tool policy and record are as before. `nylorun-interactions` adds `ask`. `nylorun migrate folder <dir> --to 3` converts an `agent-folder/2` folder; rename the tools your instructions name. `agent-folder/1` and `agent-folder/2` folders compile as before. Every agent's `triggers` answers carry `now`. See [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| An agent's own triggers (`nylorun` 0.26, Runtime 0.41)                                                                                                           | Additive. `engine: { triggers: true }` offers the root agent the `triggers` tool, and the Agent keeps what it makes: see [An agent's own triggers](/docs/run/triggers#an-agents-own-triggers). A tool policy rule of `kind: "runtime"` matches the operations the Runtime serves itself (`triggers`, `memory`, `schedule_wake`); rules without it match MCP and HTTP calls only, as before. `GET /v1/runs/stream` follows the Tenant's trigger runs. An older Runtime refuses a manifest that declares it with `400`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| A2A `metadata.removeTools` (`nylorun` 0.25.1, Runtime 0.40)                                                                                                      | Additive. A2A `SendMessage` takes `message.metadata.removeTools`, read as a session message's [`removeTools`](/docs/run/sessions#leave-tools-out-of-a-turn); `createA2aClient`'s `send()` takes `removeTools`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Engine features by declaration, secret routing and `removeTools` (`nylorun` 0.25, Runtime 0.39)                                                                  | Additive, with one behaviour change. **A tool policy rule whose `agent` is the session's agent now also matches its subagents' MCP and HTTP calls**: check `deny` and `ask` rules scoped to an agent that has subagents. `format: agent-folder/2` gives an agent only the [engine features](/docs/build/agent-manifests#engine-features) it declares (`engine:`, `memory.index`); `agent-folder/1` folders compile as before, and `nylorun migrate folder <dir> --to 2` converts one with no change to its text or tools. `nylorun check --explain` and `previewTurn()` show what an agent gets. A `bearer` or `headers` slot takes `toolPrefix`, and a slot's value write takes `via` (Host feature `secret-routing`): see [Route a slot](/docs/run/credentials#route-a-slot). A message takes `removeTools` (Host feature `remove-tools`): see [Leave tools out of a turn](/docs/run/sessions#leave-tools-out-of-a-turn). A session's view has `model`, and its log `session.model`: see [A session's model](/docs/run/models#a-sessions-model). An MCP server that failed at the first turn rejoins at a later one; the memory index refreshes when another session wrote the memory. An older Runtime refuses each new field with `400`. See [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Manifests as files, complete (`nylorun` 0.20, Runtime 0.32)                                                                                                      | Additive, with two deprecations. A folder takes `flow.json`, `agents/<id>/`, `plugins/<name>/`, `$schema` in every JSON file, `extends` in `runtime.json`, and `.nyloignore`. `nylorun check` refuses offline what only the save refused (sections that do not fit, cron schedules and time zones, `files/` off a pod) and checks every schema as JSON Schema; `approval` in a folder is `approval_removed`. A `.env` or key file is a warning, no longer a refusal, and a file with CRLF line ends compiles. **`instructions/*.md` sort naturally (`2-style.md` before `10-tone.md`): a folder with ten or more of them compiles to a different manifest, so its next `apply` saves a new version and moves the Agents that track it.** The three-file format is deprecated: `nylorun apply` and `composeManifest()` read it and warn; convert it with `npx nylorun migrate folder <dir>`. `secrets` in a `SKILL.md` is deprecated: list them in `AGENT.md`'s `skills` block (`.skills()` still reads it, with a `DeprecationWarning`; an agent manifest refuses it, and `nylorun check --fix` moves it). `session.approve()` and `respond()` take their options as optional, each making its own idempotency key. What a folder may hold is the Tenant's [Runtime limits](/docs/run/limits#agent-manifests) `folderFiles`, `folderBytes`, and `folderTextFileBytes`. An Agent whose version has a required secret with no value is `input_required` (`secret_unset`) until it is set. See [Agent manifests](/docs/build/agent-manifests) and [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Manifests as files (`nylorun` 0.19, Runtime 0.31)                                                                                                                | Additive. `PUT /v1/agent-manifests/{name}` also takes a manifest's files by hash (`application/vnd.nylorun.folder+json`): the Runtime compiles it, answers `422 folder_invalid` when it does not compile, and keeps it as the version's source (`GET /v1/agent-manifests/{name}/versions/{version}/source`). `nylorun init`, `check`, and `apply` work on `AGENT.md`; `@nylorun/agents` adds `packFolder()`, `checkFolder()`, `agentManifests.saveFolder()`, `planFolder()`, `source()`, and `sourceFile()`. Host feature `agent-folders`: an older Runtime answers the folder media type `415`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `@nylorun/cli` is `nylorun` under another name (`@nylorun/cli` 0.17)                                                                                             | `npx @nylorun/cli <command>` runs `nylorun <command>`, with the same help, output, and exit codes, and prints no deprecation line. Its `nylo` is gone: write `nylorun` in scripts. `nylorun`'s own `nylo` still exits 2 naming the `nylorun` command, and a later release removes it. Install `nylorun` or `@nylorun/cli` globally, not both: each provides `nylorun`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Gateway credentials and the workload token (Runtime 0.30)                                                                                                        | Additive (Host feature `gateway-credentials`). A `bearer` or `headers` credential with `via` takes `toolPrefix`, the prefix the gateway puts on the tools it lists: once you add it, rewrite tool policy rules and `tools` settings that used the gateway's names (`github-create_issue`) with the server's own (`create_issue`). See [Gateway tool prefix](/docs/run/credentials#gateway-tool-prefix). A gateway's report that the server behind it answered `401` (LiteLLM's `auth_required`) is now `credential_rejected` and a `failed` discovery, as a `401` is. A custom model endpoint takes `settings.headers` and `settings.callHeaders`. The credential type `workload` and the model auth `{ type: "workload" }` send the Runtime's workload token ([Docker Compose → The workload token](/docs/deploy/vm#the-workload-token)). An older Runtime refuses each with `400`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Session usage by token kind (protocol 18, Runtime 0.29)                                                                                                          | Additive for the Runtime: protocol 16 and 17 clients read usage as before. `@nylorun/agents` 0.25 and later send protocol 18 and require the Host feature `usage-by-kind`: against an older Runtime they throw `IncompatibleRuntimeError`, so restart the Tenant with the new `nylorun` first. Model calls add `startedAt`, `endedAt`, and `usage.costSplit` (`input`, `cacheRead`, `cacheWrite`, `output`); session usage adds `costSplit`, `splitCalls`, `modelTimeMs`, and `timedCalls`. A call recorded before the upgrade has no split or timing (`null`): `splitCalls` and `timedCalls` count the calls that do.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Fixes in Runtime 0.29 (`nylorun` 0.18)                                                                                                                           | A flow's HTTP stage or HTTP verifier, and an HTTP tool of an agent the manifest embeds, has its `credential` checked at save: a manifest that saved before can now be `422 manifest_inconsistent`, naming the stage. A trigger's `webhookUrl` names `NYLORUN_PUBLIC_URL` (`nylorun start` passes it). `POST /v1/webhooks/{endpointId}` ignores an `Authorization` header. `composeManifest()` keeps `harness.memory`, and `agentManifests.save({ agent, runtime, memory })` turns on a built agent's memory. Every `nylorun` command's `--help` exits 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Studio's pages (Studio 0.28 to 0.32)                                                                                                                             | Studio opens on the Agents list; the sidebar holds the Tenant and its Agents, and the Tenant has a page of its own (manifests, models, tool policy, limits, usage). An Agent's page and a session's inspector have new tabs. Old links open their new place: `/sessions`, `/settings`, `/agent-manifests`, an Agent page's `?tab=`, and a session's `?inspector=`. See [Studio](/docs/run/studio).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| A queue per session (protocol 17)                                                                                                                                | A message to a session whose turn runs, or that waits on an approval or an answer, is queued (`{ status: "queued", queuedMessageId, position }`) and starts the next turn when this one ends, each its own user message. To keep the refusal, send `delivery: "reject"` (`session.input(value, { idempotencyKey, delivery: "reject" })`, `nylorun sessions send --reject-if-busy`): it is `409 session_busy`, where it had no code. At most `sessionQueuedMessages` (100) wait; one more is `429 queue_full`. A protocol 16 client's messages are `reject` unless they say otherwise. A custom harness may get `checkpoint.input` `{ kind: "messages", messages }`: write each as its own transcript entry. See [Sessions](/docs/run/sessions#messages-while-a-turn-runs) and [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md#a-queue-per-session-protocol-17).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Triggers, webhooks and wakes (protocol 17)                                                                                                                       | Additive. `runtime.triggers` (`schedule`, `at`, `webhook`) and `runtime.selfWake` are no longer refused. Webhook deliveries arrive at `POST /v1/webhooks/{endpointId}` with no credential: publish only `/v1/webhooks/*` to the internet. New Runtime limits (`triggersPerAgent`, `triggerRunsPerHour`, `webhookBodyBytes`, and more) and Host tuning (`triggers.*`). Tool calls gain `kind: "runtime"` (`schedule_wake`, `memory`). See [Triggers and wakes](/docs/run/triggers).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Agent memory (`nylorun` 0.17)                                                                                                                                    | Additive. `harness.memory` turns it on; memories live in Postgres with the Agent, so back them up with it. New error code `memory_conflict`; new limits `memoryBytes`, `memoriesPerAgent`, `memoryIndexLines`, and `memoryIndexBytes`. See [Agent memory](/docs/run/memory).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Agents move between versions (protocol 16)                                                                                                                       | `PUT /v1/agents/{id}` naming another version of its manifest moves the Agent in place (`?dryRun=true`, `client.agents.plan()`), and a save moves every Agent that tracks it (`manifest: "name"`; `"name@n"` pins). A pod applies a runtime change at its next start on the same volume (`targetVersion`, `waitingFor`; `POST /v1/agents/{id}/restart`, `client.agents.restart()`); a failed start goes back (`failedVersion`, `agent.start_failed`, state `failing`). Name, kind, harness, and storage are fixed: `409 agent_fixed_field` replaces `409 environment_immutable`; fork to change them. The fork-to-upgrade step of the protocol 14 row is no longer needed. See [Versions](/docs/run/agents#versions).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Agents from one manifest (protocol 16, a fresh start)                                                                                                            | **Migration 0032 deletes every Environment with its disk, disk versions, and secrets, drops saved agents and environment manifests, and closes every session** (`closedReason: "protocol_16"`). Export disks before upgrading (see [From protocol 14](#from-protocol-14)). One agent manifest v8 (`PUT /v1/agent-manifests/{name}`, with `harness` and `runtime` sections, `If-Match`, and `?dryRun=true`) replaces `saveAgent` and `/v1/environment-manifests`: `nylorun migrate v8`, `nylorun apply`, `client.agentManifests.save()`, `composeManifest(dir)`. The Runtime checks the two sections against each other at save: `422 manifest_inconsistent` (`details.gaps`) replaces `409 environment_unsuitable`. `requires` leaves the API: the SDK (`ManifestGapsError`) and `nylorun apply` check it before they send. `/v1/environments/{id}` is `/v1/agents/{id}` (same sub-routes, plus `restart`), made from a saved manifest only; `ownerUserId` is `owner`; the view's `manifest` is the reference and `runtime` what it runs; `state` is the Agent's (`working`, `sleeping`, `input_required`, `failing`, `paused`) and `compute.state` its sandbox's. Sessions: `createSession({ agent, ownerUserId })` (`agentId` and `environment` before); `implementationVersion`, `definitionHash`, and `environment` leave the view. SDK: `client.environments` → `client.agents`; `environments.manifests` → `client.agentManifests`; `saveAgent` → `agentManifests.save`; `listAgents` → `agents.list`; `forSession` has no replacement; `environmentManifest` → `agentManifest`; `environmentFiles` → `runtimeFiles`; `ENVIRONMENT_EVENT_TYPES` → `AGENT_EVENT_TYPES`. CLI: `nylorun environments …` → `nylorun agents …`; `environments manifests` → `nylorun agent-manifests`; `agents save` → `nylorun apply`; `tenant reset --environments` → `--agents`; `--environment <id>` → `--agent <id>`. See [Saving manifests](/docs/run/agent-manifests), [Agents](/docs/run/agents), and [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md#agents-from-one-manifest-protocol-16-harness-api-5). |
| Names say Agent (protocol 16)                                                                                                                                    | Codes `environment_not_granted`, `_busy`, `_unavailable`, `_lost`, and `_owner_mismatch` → `agent_*`; events `environment.*` → `agent.*` (`GET /v1/agents/{id}/events`; `agent.attached` in session logs; `environment.state` and `environment.exec` keep their names); scope `environments:write` → `agents:write`, and `agent-manifests:write` to save manifests; identity file `environments:` → `agents:` (an issuer without it reaches no Agent; the old spelling stops the Runtime); `GET /v1/me` drops `environments`. AG-UI and A2A paths name an Agent; `forwardedProps.nylorun.session` takes `info` only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Budgets, coverage and reset (protocol 16)                                                                                                                        | Budget and usage scope `agent` → `manifest`, keyed by the agent manifest's name (migration 0032 renames stored budgets); `ModelCall.agentId` → `manifestName`. `admin.coverage({ agentId })` names an Agent (no `environmentId`); `admin.mcp.preview({ url, agentId })`; `admin.tenant.reset({ scope: "agents" })`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Harness API 5 (protocol 16)                                                                                                                                      | Rebuild custom harness images against `@nylorun/core` 0.24 and say `hello { api: 5 }`; core refuses `api: 4`. `turn.start.agent` (the Agent the session runs on) replaces `turn.start.environment`, and `routing.sandbox.environmentId` is the Agent's id. `turn.start.definition { name, version }` names the agent manifest version, and `turn.start.loop` carries the harness section's `loop`. `manifest` is that version's harness section in agent manifest v7's shape, with the manifest's name as its `id`. A session's harness is its Agent's manifest's `harness.id`, and a custom harness runs only as a pod Agent's image (`harness.id`, `runtime.kind: "pod"`, `image`): see [Kubernetes](/docs/deploy/kubernetes#custom-harnesses) and [Harness API](/docs/build/harness-api).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Harness API 4 (protocol 15)                                                                                                                                      | The manifest has no `runtime` block: the harness writes the model's instructions and defines its tools from the facts in `turn.start`, and runs the artifact and skill tools itself, over `artifact.read`, `artifact.write` (with a folder mode and `limits.folderEntries`), and `definition.file`; the error code `not_found` is new. Every tool call names its `target`, part of the request hash: `{ kind: "mcp", server, tool }` with the raw tool name, `{ kind: "http", tool }`, `sandbox`, or `harness`. `hello.features.tools` and the target kind `platform` are gone, no tool name is reserved, and an undiscovered MCP tool is `tool.unknown`. `turn.start.model` describes the model; the Model Gate only fetches and translates files (`unsupported_input`), and `ModelCall` has no `outputSchema`. `turn.start.mcp` (raw names, `enabled`, a `deferred` hint) replaces `sessionTools` and `routing.mcpSnapshot`; `session.mcp` answers `{ mcp? }` and the snapshot is `snapshotSchemaVersion: 2`; the harness names, defers, and searches MCP tools. Core shapes no tool result and refuses an outcome past `recordEntryBytes`. Core mounts no skill folder and exports no outputs (`artifact.export.skipped` and `artifact.export.failed` are claims), and `workspace.read`'s listing and bytes calls are gone. Compaction is a transcript edit marked `kind: "compaction"`, naming its summary calls (`purpose: "summary"`); `context.compacted` has no `partial`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| The harness boundary (protocol 15, a fresh start for sessions)                                                                                                   | Agent sessions opened before it are closed (`closedReason: "protocol_15"`, `409 session_closed`). `read_artifact`, `save_artifact`, `load_skill`, `read_skill_resource`, `tool_search`, and the sandbox tools are our harness's (`kind: "harness"`). No tool name is reserved: our harness fails a turn whose tools share a name with one of its own (`agent.build-failed`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Tool policy names MCP tools by server and tool (protocol 15)                                                                                                     | Rewrite `{ "tool": "github__create_issue" }` as `{ "server": "github", "tool": "create_issue" }`. A `tool` with `__` is `400`; **a stored policy with one fails closed**: every MCP and HTTP call is `tool.denied` naming the rule, and `GET /v1/tenant/tool-policy` is `409 request_rejected`, until you put it again. Approvals say `Approve <server> / <tool>?`; tool call rows add `tool`. See [Tool policy](/docs/run/tool-policy).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Any file may be sent (protocol 15)                                                                                                                               | `422 attachment_unsupported` and its code are gone: a message may name any file within the artifact limits, and the harness decides how the model sees it. The Model Gate refuses a part the model cannot take (`unsupported_input`) and a file it cannot fetch (`invalid_request`). `read_artifact` of an unreadable type is `artifact.unsupported`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Runtime limits and Host tuning (`nylorun` 0.16)                                                                                                                  | Sizes, counts, and deadlines are Tenant settings (`PUT /v1/tenant/limits`, `admin.settings.limits`, `nylorun tenant settings limits`); a `PUT` replaces all of them. A record write past `recordEntryBytes` is `413 limit_exceeded`. `NYLORUN_FLOW_MAX_*` are gone: set `flowConcurrency`, `flowMapItems`, and `flowLoopIterations`. Process timings are `NYLORUN_TUNING`, and the CLI's `NYLORUN_CLI_TUNING`; an unknown key stops the process. Skills hold up to 2 GiB each (`PUT /v1/tenant/skills`). Studio no longer caps uploads at 32 MiB. Removed exports (`MAX_MODEL_CALL_BYTES`, `HTTP_TOOL_MAX_TIMEOUT_MS`, and others): read `RUNTIME_LIMIT_DEFAULTS`. See [Runtime limits](/docs/run/limits) and [Host tuning](/docs/deploy/vm#host-tuning).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Shell credential value (`nylorun` 0.16)                                                                                                                          | An `environment_secret` reads `nylorun_managed` in the sandbox (it read `nylorun-managed`). Change scripts that test for the literal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| HTTP tools take GET, DELETE and path parameters (`nylorun` 0.15.1)                                                                                               | Additive. See [Tools](/docs/build/tools).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Environments never change (protocol 14)                                                                                                                          | `PUT /v1/environments/{id}` on an existing Environment changes only `labels` and `ownerUserId`. A field that matches what it runs is accepted, so get-or-create still works; anything else is `409 environment_immutable`, with `details.fields`. To change what an Environment runs, fork it with `client.environments.fork()` (`POST /v1/environments/{id}/fork`) from a new manifest version, and point new sessions at the new id. The view's `recipe` is `manifest`, with `manifestName`, `manifestVersion`, `manifestHash`, and `slots`; `version` and `appliedVersion` no longer move. In `@nylorun/agents`, `EnvironmentRecipeInput` is `EnvironmentInput`. Studio edits only labels and the owner guard. Since protocol 16, Agents move between versions in place: see the Agents move between versions row. See [Saving manifests](/docs/run/agent-manifests) and [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md#environment-manifests-and-environments-that-never-change-protocol-14).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Secret slots and `requires` (protocol 14)                                                                                                                        | On an Environment whose manifest declares `secrets`, write each secret as `{ value }` (or `{ headers }`); a name it does not declare is `409 secret_not_in_manifest`. Environments without slots take typed writes as before. An agent with `.requires()` is refused when a session opens on an Environment that lacks what it needs (`409 environment_unsuitable`, `details.missing`); agents without it are unaffected. Since protocol 16, the SDK and `nylorun apply` check `requires` before a save, and the Runtime checks the sections at save (`422 manifest_inconsistent`): see the Agents from one manifest row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Parallel turns (protocol 14)                                                                                                                                     | A second session's turn on an Environment is no longer `409 environment_busy`; one turn per session stays. If your app relied on the refusal, send one session's message at a time yourself, or give each piece of work its own Environment or fork. `environment_busy` answers stop, reset, snapshot, and restore while a turn runs, and a turn while a disk copy runs. Sandbox commands of different sessions run at the same time; each session's keep their order. The code is `agent_busy` since protocol 16, and since protocol 17 a session queues its own messages: see the Names say Agent and queue rows.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Egress on the Environment (protocol 14)                                                                                                                          | `egress.connection` is gone from session logs, and turn traces have no `CONNECT` span. Every connection is `environment.egress` on the Environment's events, with `runningTurns`. Read a turn's egress with `client.environments.events(id, { types: ["environment.egress"], since, until })`. Since protocol 16, read `agent.egress` with `client.agents.events()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Skill folders per version (protocol 14)                                                                                                                          | A skill's files are under `/skills/<name>@<hash>/`, not `/skills/<name>/`. A `SKILL.md` that names `/skills/<name>/` should use paths relative to its own folder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| One `nylorun` command (`nylorun` 0.15)                                                                                                                           | `nylo status` → `nylorun status`; `nylo reset` → `nylorun tenant reset`; `nylo access signing-keys` → `nylorun tenant signing-keys`; `nylo configure` → `nylorun tenant models set`; `nylo doctor sandbox` → `nylorun doctor sandbox`; `nylorun key put\|list\|rm` → `nylorun tenant keys …`; `nylorun mcp inspect` → `nylorun tenant mcp inspect`; `nylorun sandbox ls\|rm` → `nylorun agents list\|rm`; `nylorun sandbox enable\|disable\|status` → `nylorun local sandbox …`; `nylorun logs`, `ls`, `delete`, `reset`, `telemetry` → `nylorun local …`. In scripts, replace `npx -p nylorun nylo <command>` with `npx nylorun <command>`. `nylo env` has no replacement: the SDKs read the Project link; outside the project, give the process its own key (`nylorun tenant keys put <id>`) and the URL `nylorun status` prints. Old spellings exit 2 naming the new one. `nylorun local reset` deletes a local Tenant's volumes, directory, and vault key; `nylorun tenant reset` clears its data and keeps the Tenant and its keys. See [CLI](/docs/run/cli).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Flat agent manifest v7 (protocol 13, a fresh start)                                                                                                              | Rebuild and save every agent: manifests v3 to v6 and a `capabilities` field are refused. Sessions opened before protocol 13 are closed: their history stays readable and a new turn is `409 session_closed`. `capabilityId` is gone from `tool.completed`, `mcp.discovered`, tool call rows, and the Harness API; an HTTP tool's `server` is its URL's host. `Agent.from(json, { tools })` takes implementations keyed by tool name, and `binding.declarations` is `binding.parts`. A tool may not take a Runtime tool's name (`bash`, `read`, `write`, `edit`, `grep`, `glob`, `save_artifact`, `read_artifact`, `load_skill`, `read_skill_resource`, `tool_search`, `tool_call`) or contain `__`, and names are unique across tools, skills, and servers. The `runtime` block is the Runtime's: a definition that sets it is refused. Since protocol 15 no tool name is reserved and there is no `runtime` block, and since protocol 16 v7 is refused: see those rows. Names are unique within tools, within skills, and within servers, not across them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Harness API 3 (protocol 13)                                                                                                                                      | `hello.capabilities` → `hello.features` (`features.tools`, `features.workspace`); `createHarness({ capabilities })` → `createHarness({ features })`. Core refuses `api: 2`. A native tool is known by its name, and one whose name is taken fails the turn at its start. Rebuild custom harness images. Superseded by Harness API 5: see that row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Step middleware and capability bundles removed                                                                                                                   | `.use()`, `middleware()`, and `StepMiddleware` are gone: use the Tenant's [tool policy](/docs/run/tool-policy), an output schema, or your own harness. `.capability()`, `capability()`, and `CapabilityBuilder` are gone: to reuse tools and instructions, write a function that adds them (`const billing = (agent) => agent.tools(refund).instructions(BILLING)`); a bundle you publish is a plugin. The standalone `skills(dir)`, `plugin(dir)`, and `mcp(servers)` → `.skills(dir)`, `.plugin(dir)`, `.mcp(servers)`; `.skills(dir, { id })` → `.skills(dir)`. `model()` is gone: the Runtime picks the model. The `middleware.*` events are gone.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Tool calls traced (protocol 13)                                                                                                                                  | `tool.completed` and tool call rows gain `skill` and `plugin`, and `mcp.discovered` names each server's `plugin`. A tool the turn's harness declared is `kind: "harness"`; it said `platform` before.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Model inputs and files (protocol 12)                                                                                                                             | **A custom endpoint reads text only by default.** If yours reads images, set `settings.inputs: ["image"]` on `PUT /v1/tenant/model` (`pdf`, `audio`, and `video` too). A message naming a file the Tenant's model does not read is `422 attachment_unsupported` at accept, and no turn starts. After its turn a file is a reference line the model reads again with `read_artifact`. Every agent has `read_artifact`, so a session's `manifestHash` differs from its `definitionHash`. Since protocol 15 any file may be sent, and since protocol 16 `definitionHash` is gone: see those rows. See [Files](/docs/run/files).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Environments replace sandboxes and vaults (protocol 11)                                                                                                          | **The upgrade deletes sandboxes, their disks, and every vault except the Tenant's model vault, and closes open sessions.** Their history stays readable; a new turn is `409 session_closed`. Before upgrading, list `/v1/sandboxes`, `/v1/tenant/vaults`, and each vault's credentials with the old release; secret values cannot be exported, so have them at hand. Upgrade the Runtime, `@nylorun/agents`, `@nylorun/admin`, `nylorun`, and Studio together. Then recreate Environments and write their secrets. Renames: `client.sandboxes` → `client.environments`; `createSession({ sandbox, vaultIds, credentialSelections })` → `createSession({ environment })`; `admin.vaults` → `client.environments.secrets` and `admin.coverage({ agentId, environmentId })`; `admin.mcp.preview({ vaultId })` → `{ environmentId }`; `network.allow` → `network.allowedHosts`; `lifecycle.ttl` and `onExpiry` → `lifecycle.deleteAfter`; `sandbox_busy`, `sandbox_unavailable`, `sandbox_lost`, `sandbox_not_granted` → `environment_*` (`sandbox_expired` is gone); `sandbox.*` events → `environment.*`; scope `sandboxes:write` → `environments:write`; identity-file `sandboxes:` → `environments:`; `nylorun mcp inspect --vault` → `--environment`; `nylo reset --sandboxes` → `--environments` (both commands moved again in `nylorun` 0.15: see the one-command row). On Kubernetes, delete the dropped sandboxes' pods: `kubectl delete sandboxes.agents.x-k8s.io --all -n <namespace>`. These names changed again in protocol 16: see the Names say Agent row. See [Agents](/docs/run/agents) and [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md#environments-replace-sandboxes-and-vaults-protocol-11-a-fresh-start).                                                                                                                                                                                                                                                                                                                                                                     |
| Tool policy replaces `approval`                                                                                                                                  | Saving a definition that sets `approval` is refused, and `http({ approval })` and `.mcp({ … approval })` throw. Remove `approval` and move each `approval: "always"` to an `ask` rule with `admin.toolPolicy.put({ rules })`; since protocol 15 a rule for an MCP tool names `server` and `tool`. Approving a held call is unchanged. See [Tool policy](/docs/run/tool-policy).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Tool calls delivered at least once                                                                                                                               | A crash or lost connection sends an MCP or HTTP call again with the same key (`Idempotency-Key`, or `_meta["nylorun/idempotency-key"]` for MCP), up to three sends; then the model gets `tool.interrupted`. An interrupted sandbox command fails as `tool.interrupted` at once. No tool call is `uncertain`, and `mcp.lost` reaches the model for every MCP tool. Make side effects honor the key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Harness id `nylorun`                                                                                                                                             | A harness that says `@nylorun/harness` in `hello` is refused: upgrade the harness image with the Runtime (`nylorun start` does it on a local Tenant). An event's `source.kind` is `client`, `harness`, or `core`; events written before say `api` or `loop`, so accept both.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| New session log rows                                                                                                                                             | A model step that said nothing writes an empty `message.assistant`, and a long compaction writes partial `context.compacted` rows. New types: `node.completed`, `egress.connection`, and `environment.egress` (`egress.connection` left session logs in protocol 14: see the egress row; `environment.egress` is `agent.egress` since protocol 16). Skip empty assistant messages with `isEmptyAssistantMessage` from `@nylorun/core/contracts`; ignore types you do not know.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Runtime image path                                                                                                                                               | The image's entry point is `/app/runtime/server/dist/host/main.js`, not `/app/runtime/dist/host/main.js`. Update anything that runs a file under `/app/runtime/dist/`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Error wording                                                                                                                                                    | The refusal for a code tool, the hooks error, and `nylo endpoints` now say the Runtime runs agents from their manifests alone. Match on the code, not the old text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `nylo` ships in `nylorun` (`nylorun` 0.13)                                                                                                                       | Run `npx -p nylorun nylo <command>`, or `npx nylo` with `nylorun` as a devDependency. `@nylorun/cli` forwards with a warning and will be removed. Replaced in `nylorun` 0.15: see the one-command row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `@nylorun/admin/project` removed (`nylorun` 0.13)                                                                                                                | Import `@nylorun/core/project`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `AdminError.code` follows the status (`nylorun` 0.13)                                                                                                            | Without a Runtime error body, `code` is `invalid_request` for `400`, `credential_invalid` for `401`, `not_found` for `404`, `unsupported_media_type` for `415`, `internal_error` for `5xx`, else `request_rejected`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| MCP credentials from vaults only (protocol 10)                                                                                                                   | MCP OAuth sign-in, the `oauth` credential type, `admin.vaults.startOAuth`, `nylorun mcp connect`, and the credential resolver (`NYLORUN_RESOLVER_URL`, `NYLORUN_RESOLVER_TOKEN`) are gone. The upgrade deletes every `oauth` credential: list each vault's credentials first. Since protocol 16, credentials are an Agent's secrets: follow the Agents from one manifest row and [Secrets and credentials](/docs/run/credentials).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Tool and MCP server names (protocol 10)                                                                                                                          | Saving an agent refuses a tool or MCP server name outside `^[A-Za-z0-9_-]{1,64}$`. Rename it and save again. The model calls MCP tools as `server__tool`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Coded tool errors (protocol 10)                                                                                                                                  | A `401` from an MCP server or HTTP tool is `credential_rejected` and is not retried. MCP failures are coded errors such as `mcp.unreachable`. For a lost call, see the at-least-once row above. See [MCP](/docs/build/mcp#errors).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Refused credentials are `401` (protocol 9)                                                                                                                       | A missing key is `401 credential_required` and an unknown key or token `401 credential_invalid`, not `404`. A request with neither `Nylorun-Protocol` nor `Authorization` is `401`, not `426`. Keep `WWW-Authenticate` at your proxy and forward `/.well-known/oauth-protected-resource`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Identity file (protocol 9)                                                                                                                                       | `maxLifetime` is ignored; the Runtime checks `exp` only. `subject`, `scopes`, and `allowedScopes` are optional; if you leave out `subject`, the owner is the bare `sub`. Unknown keys are logged and ignored.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Stricter agent checks                                                                                                                                            | `Agent.from` checks with the Runtime's manifest schema and refuses unknown fields and invalid names with `agent.build-failed`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Project link lookup                                                                                                                                              | Clients find the nearest `.nylorun/` from the working directory upward, never at or above the home directory. An invalid link or `credentials.json` is `connection_missing`, naming the file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Harness model adapters removed                                                                                                                                   | `@nylorun/harness/model/adapters` and `preparedModel` are gone. An in-process `run()` passes `onModelCall`, for example `piModel` from `@nylorun/runtime/node`. Agents the Runtime runs are unaffected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Manifest-only agents (protocol 8, manifest v5)                                                                                                                   | The Runtime never calls your code during a session. Hooks, Action endpoints (`createActionHandler`, `/v1/endpoints`), tool code, and stdio MCP servers are gone: tools are HTTP tools and remote MCP servers, and flows use `pipe`, `switch`, `parallel`, `map`, and `loop` without functions. Rebuild and save your agents, then start new sessions; a v4 manifest is refused. See [MIGRATION.md](https://github.com/nylorun/agents/blob/main/guides/MIGRATION.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Runtime API and Management API (protocol 8)                                                                                                                      | `/v1/tenant/*` takes a management key only; use `createAdmin()` from `@nylorun/admin`. Vaults moved to `/v1/tenant/vaults` (removed in protocol 11) and signing keys to `/v1/tenant/signing-keys`. The Admin API, its port (`8788`), `NYLORUN_ADMIN_*`, and `admin-openapi.json` are gone; use `npx nylorun` on the machine, or `nylorun-operate` in a self-hosted container. The `tenant:settings` scope grants nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Open-source auth (protocol 7)                                                                                                                                    | Servers use keys from `npx nylorun key put` (now `nylorun tenant keys put`: see the one-command row); browsers and apps present your identity provider's JWTs (a trusted issuer). Subject tokens, publishable keys, `createBrowserClient`, derived keys, and `vaults:own` are gone.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Executors removed (protocol 3)                                                                                                                                   | `connectAgents`, `NYLORUN_EXECUTOR_KEY`, `/v1/executors`, and claims are gone. The Action endpoints that replaced them were removed in protocol 8: use HTTP tools and remote MCP servers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| One Tenant per installation                                                                                                                                      | A Runtime serves one Tenant. There is no `tenant` option on `createClient`, and no `nylo tenant create` / `tenant use`. `nylorun start` in a project creates and links that project's Tenant.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Sandboxes moved to sessions                                                                                                                                      | `.sandbox()` on an agent is gone. Since protocol 16, a session runs on an Agent: follow the Agents from one manifest row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Builder deprecations                                                                                                                                             | Options-form `Agent({ id, instructions, tools })` and `.use()` print a `DeprecationWarning`. Use `.instructions()`, `.tools()`, `.capability()`, `.mcp()`, `.skills()`, or `.plugin()`. `.use()` and `.capability()` are now removed: see the step middleware row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Flows run no code (workflow manifest v3)                                                                                                                         | Build flows as `Agent({ id }).pipe(…)`. Stage `input` functions, `switch` `on`, loop `verify` functions and `decide` are gone: shape data with each agent's `.output()`, route on `route`, map over `items`, and verify with an agent or `http({ url })`. `.step()` is a deprecated alias of `.pipe()`. `Chain`, `Switch`, `Parallel`, `Map`, `Loop`, `withInstructions`, and `withoutTools` are removed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `nylorun reset`                                                                                                                                                  | Deletes this Tenant's data only. `nylorun delete <name> --yes` removes the Tenant. Now `nylorun local reset` and `nylorun local delete`: see the one-command row.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

Release notes are on
[GitHub releases](https://github.com/nylorun/agents/releases).

## Next step [#next-step]

<Cards>
  <Card title="Quickstart" description="Start the Runtime, then connect with a client." href="/docs" />

  <Card title="Troubleshooting" description="Fix a connection or incompatible Runtime." href="/docs/troubleshooting" />
</Cards>
