NylorunDocsBeta
More

Compatibility

Package versions, protocol range, upgrades, and breaking changes.

Pre-1.0: expect breaking changes

Nylorun is in beta. APIs, specs, and on-disk formats change. Upgrade packages as a family and read the breaking changes below.

Package or imageVersion
nylorun0.32.0-beta
@nylorun/cli (nylorun under another name)0.17.51-beta
@nylorun/create-agent0.16.53-beta
@nylorun/agents0.42.0-beta
@nylorun/admin0.21.0-beta
@nylorun/core0.50.0-beta
@nylorun/harness0.37.1-beta
@nylorun/runtime / ghcr.io/nylorun/runtime0.56.0-beta
ghcr.io/nylorun/studio0.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 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

  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

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); 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.

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.

Migration 0032 deletes every Environment

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:

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.

Breaking changes

ChangeWhat 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. 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.
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.
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 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 and 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.
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.
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.
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.
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, 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.
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. 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; 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 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. A message takes removeTools (Host feature remove-tools): see Leave tools out of a turn. A session's view has model, and its log session.model: see A session's 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.
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 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 and 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. 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). 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.
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 and MIGRATION.md.
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.
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.
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.
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). 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, Agents, and MIGRATION.md.
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 and 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.
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 and 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.
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 and MIGRATION.md.
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.
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, 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.
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 and MIGRATION.md.
Tool policy replaces approvalSaving 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.
Tool calls delivered at least onceA 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 nylorunA 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 rowsA 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 pathThe 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 wordingThe 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.
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.
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 checksAgent.from checks with the Runtime's manifest schema and refuses unknown fields and invalid names with agent.build-failed.
Project link lookupClients 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.
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 installationA 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 deprecationsOptions-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 resetDeletes 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.

Next step

On this page