Migrate from 0.18 to 0.19

Harness 0.19 is a breaking pre-1.0 release. Upgrade the tested package set together; do not mix protocol-1 clients with a protocol-2 Runtime Host.

Upgrade packages and scripts

Keep @nylorun/agents in dependencies. Move CLI and Studio to devDependencies; application code no longer depends on @nylorun/runtime. Operator applications can add @nylorun/admin@0.2.0-beta.

Install the Runtime separately. The CLI does not download it:

node --version
npm install --global @nylorun/runtime@0.10.0-beta
npx nylorun doctor runtime

The Runtime supports macOS and Linux. On Windows, install it inside WSL2 and keep Projects in the Linux filesystem.

Replace the compiled entry:

  "scripts": {
    "dev": "nylorun dev",
-   "studio": "nylorun studio",
-   "start": "nylorun serve"
+   "studio": "nylorun-studio",
+   "start": "node dist/src/main.js"
  }

Add src/main.ts:

import { connectAgents } from "@nylorun/agents";
import { agents } from "../agents/index.js";

await connectAgents({ agents }).ready;

Ensure the TypeScript build emits that file to dist/src/main.js.

Move from Project Runtime to Host and Tenant

The old Project .nylorun/ directory held SQLite, Runtime credentials, pid, logs, and vault data. The new layout is:

• Host root: NYLORUN_HOME or ~/.nylorun.
• Tenant data: <host root>/tenants/<tenantId>/.
• Project link: .nylorun/link.json plus .nylorun/credentials.json.

Stop the old Runtime, preserve a backup of its .nylorun/ directory, upgrade, then run nylorun runtime up followed by nylorun dev. The CLI creates a new Tenant or lets you select an existing one and writes the Project link.

Old SQLite checkpoints and session/event files are not automatically imported. Keep backups for audit needs and start new sessions after upgrading.

Update clients and HTTP calls

Every Tenant request now requires protocol 2 and an explicit Tenant:

import { createClient } from "@nylorun/agents";

const client = createClient({
  url: process.env.NYLORUN_RUNTIME_URL!,
  key: process.env.NYLORUN_SERVER_KEY!,
  tenant: process.env.NYLORUN_TENANT!,
});

The SDK sends Nylorun-Tenant and Nylorun-Protocol. Code that performs raw HTTP must send both. Move model routes from /v1/host/* to /v1/tenant/* and replace startup executor configuration with PUT /v1/executors or connectAgents.

With no arguments, createClient() and connectAgents() resolve environment variables first and then the nearest Project link. A partial explicit or environment connection is an error rather than a signal to fall through.

Replace CLI commands

nylorun studio, nylorun-studio, and development --no-studio remain supported. Hosted Studio is the default; use --local-ui for Safari or offline work.

Verify the migration

1. Run nylorun doctor runtime, npm run check, and npm run build.
2. Run nylorun runtime status and confirm protocol 2 and the intended Tenant.
3. Run nylorun tenant current, then npm run dev.
4. Open a new Studio session and exercise one tool or workflow.
5. Stop the application and confirm the Host remains available before using nylorun runtime down.