@nylorun/create-agent 0.8.1-beta → 0.10.0-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,49 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.10.0-beta
4
+
5
+ ### Minor Changes
6
+
7
+ - bf1c2da: **The local Runtime and Studio run as a Docker Compose stack that the CLI manages; Studio ships only as its image (breaking beta).**
8
+
9
+ - `nylorun start` writes `<Host root>/stack/compose.yaml` and `.env` (mode 0600) and starts Postgres, Restate, s2-lite, the Runtime and Studio on loopback ports, with the Runtime and Studio images this CLI pins (`nylorun.runtime`, `nylorun.studio`; `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them). `nylorun stop` keeps the volumes; `nylorun status [--json] [--env]` reports services and health; `nylorun reset [--yes]` deletes the volumes and every Tenant.
10
+ - `nylorun dev` starts the stack if it is not running, creates the Project's Tenant on first run, opens Studio on that Tenant through a single-use login URL (`next=/tenants/<id>`), and runs the application with `NYLORUN_RUNTIME_URL=http://localhost:<port>`. `--no-open` prints the URL only; `--no-studio` skips Studio. `--local-ui` is removed (exit 2).
11
+ - `nylorun logs` and `nylorun studio` are the stack commands (`nylorun stack <command>` still works). `nylorun studio` lands on the linked Project's Tenant.
12
+ - `nylorun runtime up|down|restart|run|status|logs` and the `up`/`down` aliases are removed; they exit 2 and name `nylorun start|stop|status|logs`. `nylorun runtime status --env` is now `nylorun status --env`.
13
+ - `nylorun doctor` checks Node 24+, Docker, Compose v2 and the stack's health; `doctor runtime` is an alias of it.
14
+ - `@nylorun/studio` is private and ships only as `ghcr.io/nylorun/studio`: `startStudio`, the hosted (`local.nylorun.studio`) and local UI modes, pairing, the `nylorun-studio` bin and the UI bundle download are removed.
15
+ - `npm create @nylorun/agent` no longer adds `@nylorun/studio` or a `studio` script, checks for Docker with Compose v2 instead of a global `@nylorun/runtime`, and accepts `--no-studio` only as a deprecated no-op.
16
+
17
+ - ba1b239: **`nylorun` sets up the local stack; `@nylorun/cli` becomes the Runtime client `nylo` (breaking beta).**
18
+
19
+ - New unscoped package **`nylorun`**: `npx nylorun up` sets up the Docker stack on the first run and starts it after that, from any directory; `npx nylorun down` stops it (volumes are kept). `up` and `down` are aliases of `start` and `stop`. It also owns `status`, `logs`, `studio`, `reset` and `doctor`, pins the Runtime and Studio images (`package.json` `nylorun.runtime` / `nylorun.studio`), depends on `@nylorun/core` only, and never creates Tenants.
20
+ - **`@nylorun/cli`** is the Runtime client with the command **`nylo`**: `nylo tenant create [name]` (creates the Tenant; in a project, writes the Project link and seeds the model provider and sandbox from `.env`), `nylo tenant current|list|use|status|reset|delete`, `nylo configure`, `nylo env` (was `nylorun status --env`) and `nylo doctor sandbox`. It no longer provides the `nylorun` command or the stack commands.
21
+ - **Removed:** `nylorun dev` and `nylorun dev --ephemeral`. Link once with `nylo tenant create`, then run the project's own `npm run dev`. Moved commands exit 2 and name their replacement.
22
+ - **Starter:** the generated project depends on `@nylorun/agents` only (no Nylorun devDependency); `dev` is `tsx watch --env-file-if-exists=.env src/main.ts`. `npm create @nylorun/agent` installs the project and prints the next steps (`npx nylorun up`, `npx @nylorun/cli tenant create`, `npm run dev`) instead of starting development; `--no-open` is accepted and ignored.
23
+ - `connectAgents` names those steps when it finds no Runtime connection. Runtime repair hints, model errors and core's sandbox message name `nylo` and `nylorun up`.
24
+
25
+ - 1d84b3e: **Native Windows is no longer supported; Windows developers use WSL2.** Nylorun runs on macOS and Linux. On native Windows, `nylorun` and `npm create @nylorun/agent` stop with WSL2 guidance. Install Node 24 and Docker (Docker Desktop's WSL integration) inside your WSL distribution and keep projects in its Linux filesystem. The Windows-only process handling (`taskkill`, `.cmd` shims, `npm.cmd`) is removed. `nylorun doctor` reports WSL as `Linux (WSL: <distribution>)`.
26
+
27
+ ### Patch Changes
28
+
29
+ - Update the tested Harness, SDK, Runtime, and CLI compatibility combination.
30
+
31
+ ## 0.9.0-beta
32
+
33
+ ### Minor Changes
34
+
35
+ - c49efed: **Breaking (pre-1.0 minor):** Generated starter matches Runtime Clients layout.
36
+
37
+ - Adds `src/main.ts` with `connectAgents({ agents })`.
38
+ - `start` → `node dist/src/main.js`; `studio` → `nylorun-studio`.
39
+ - `@nylorun/cli` and `@nylorun/studio` move to `devDependencies`; production depends on `@nylorun/agents` (and `zod`) only.
40
+ - `--no-studio` removes Studio without rewriting `dev`.
41
+ - Before `npm run dev`, checks the prerequisites (Node 24+ and `nylorun-runtime` on PATH). If one is missing, it stops after creating the project and prints the install commands; it never installs them.
42
+
43
+ ### Patch Changes
44
+
45
+ - Update the tested Harness, SDK, Runtime, and Studio compatibility combination.
46
+
3
47
  ## 0.8.1-beta
4
48
 
5
49
  ### Patch Changes
package/README.md CHANGED
@@ -1,26 +1,70 @@
1
1
  # @nylorun/create-agent
2
2
 
3
+ Install the prerequisites first (the creator checks them and never installs
4
+ them): Node 24 or newer, and Docker with Compose v2 ([Docker
5
+ Desktop](https://docs.docker.com/get-started/get-docker/),
6
+ [OrbStack](https://orbstack.dev) or [Colima](https://github.com/abiosoft/colima)).
7
+ The local Runtime and Studio run as a Docker Compose stack that `nylorun`
8
+ manages. On Windows, work inside
9
+ [WSL2](https://learn.microsoft.com/windows/wsl/install) with Docker Desktop's WSL
10
+ integration; native Windows is not supported.
11
+
3
12
  ```sh
13
+ node --version # 24 or newer
14
+ docker compose version # v2
4
15
  npm create @nylorun/agent@beta my-agent
5
16
  ```
6
17
 
7
- Creates a Node 24 project with `@nylorun/agents`, `@nylorun/cli`, Zod, and optional Studio. The registry in `agents/index.ts` exports agent definitions. The starter includes one ordinary `lookup_order` tool; ask “Look up order demo-123”.
18
+ Creates a Node 24 project whose only Nylorun dependency is `@nylorun/agents`
19
+ (plus Zod). The registry in `agents/index.ts` exports agent definitions.
20
+ `src/main.ts` calls `connectAgents` for both `npm run dev` and `npm start`. The
21
+ starter includes one ordinary `lookup_order` tool; ask “Look up order
22
+ demo-123”.
8
23
 
9
- Creation installs dependencies and starts development. Use `-- --no-studio` for headless development or `-- --no-open` to suppress browser opening. `--yes` affects installation only. The first `nylorun dev` or `nylorun serve` starts the local Runtime and asks for the model provider when the terminal is interactive and stores the credential in the Runtime vault. A non-interactive start without a credential exits and names that setup. `NYLORUN_DEV_MODEL=fixture` skips it.
24
+ Creation installs the project's dependencies and prints the next steps. If a
25
+ prerequisite is missing (Node older than 24, no `docker`, an engine that does
26
+ not answer, or Compose older than v2), it says what to set up first. `--yes`
27
+ affects installation only. `--no-open` and `--no-studio` are accepted and
28
+ ignored: the creator starts nothing and opens no browser.
10
29
 
11
30
  ```sh
12
31
  cd my-agent
13
- npm run dev
32
+ npx nylorun@beta up # the local Runtime and Studio (Docker)
33
+ npx @nylorun/cli@beta tenant create # this project's Tenant, linked in .nylorun/
34
+ npm run dev # tsx watch src/main.ts
35
+ npx nylorun studio # a fresh Studio login on this project's Tenant
14
36
  npm run build
15
37
  npm start
16
38
  ```
17
39
 
18
- Development restarts the Runtime and connected executor on source changes. `npm start` runs `nylorun serve`, which uses `dist/agents/index.js` and runs headless. Studio can attach separately and can replace an API-key credential. `nylorun configure` replaces the credential against an already running Runtime. Local Runtime credentials, the vault, and SQLite are stored in gitignored `.nylorun/`. Definitions have no model provider or `agent.run()`.
40
+ `nylorun` sets up and runs the local stack; it never creates Tenants.
41
+ `@nylorun/cli` (command `nylo`) is the Runtime client: `tenant create` creates
42
+ the project's Tenant, writes the Project link and application credentials to
43
+ gitignored `.nylorun/`, and seeds the model provider from `.env`
44
+ (`MODEL_PROVIDER`, `MODEL`, `MODEL_PROVIDER_API_KEY`) into the Tenant vault.
45
+ Studio or `npx @nylorun/cli configure` sets or replaces the provider.
46
+ `npm start` runs `node dist/src/main.js` with the same entry as development.
47
+ Export the Project environment (`eval "$(npx @nylorun/cli env)"`) before a
48
+ production start when there is no Project link. Tenant data, including the
49
+ vault, lives in the stack. Definitions have no model provider or
50
+ `agent.run()`.
19
51
 
20
- `starter/` is the canonical template. `compatibility.json` pins core, harness, SDK, Runtime, Studio and CLI. The examples recipe adds local package dependencies. Run `npm run examples:sync` after template changes, then `npm install --prefix examples`. Sync preserves authored agents, tests, credentials, and local state; it rejects conflicting edits to generated files.
52
+ `starter/` is the canonical template. `compatibility.json` pins core, harness,
53
+ agents, admin, Runtime and CLI. `nylorun` pins the Runtime and Studio images
54
+ it runs (`nylorun/package.json` `nylorun`). The examples recipe adds local
55
+ package dependencies. Run `npm run examples:sync` after template changes, then
56
+ `npm install --prefix examples`. Sync preserves authored agents, tests,
57
+ credentials, and local state; it rejects conflicting edits to generated files.
21
58
 
22
- The default examples registry contains the release starter. Advanced examples remain outside that registry for later migration.
59
+ The default examples registry contains the release starter. Advanced examples
60
+ remain outside that registry for later migration.
23
61
 
24
- After building, `node create-agent/scripts/smoke-starter.mjs` installs packed packages outside the workspace and checks the actual Studio/tool workflow, history, reload, source restart, compiled start, headless mode, and shutdown. It uses a deterministic fixture without live provider calls. Browser checks require Chrome (or `NYLORUN_CHROME_PATH`).
62
+ `npm run test:starter` (`create-agent/scripts/smoke-starter.mjs`) packs the
63
+ workspace, scaffolds the starter from the packed creator, installs `nylorun`
64
+ and `@nylorun/cli` beside it (never into it), runs `nylorun up`, then
65
+ `nylo tenant create` and `npm run dev` against a temporary local Docker stack,
66
+ then runs one turn on a temporary fixture-model Tenant and checks that it is
67
+ deleted.
25
68
 
26
- See [RELEASING](../RELEASING.md) for the Changesets beta workflow. Nothing is published by the smoke check.
69
+ See [RELEASING](../RELEASING.md) for the Changesets beta workflow. Nothing is
70
+ published by the smoke check.
@@ -1,8 +1,8 @@
1
1
  {
2
- "harness": "0.18.0-beta",
3
- "studio": "0.8.0-beta",
4
- "runtime": "0.9.0-beta",
5
- "agents": "0.5.0-beta",
6
- "core": "0.4.0-beta",
7
- "cli": "0.2.1-beta"
2
+ "harness": "0.19.1-beta",
3
+ "runtime": "0.11.0-beta",
4
+ "agents": "0.7.0-beta",
5
+ "admin": "0.3.0-beta",
6
+ "core": "0.6.0-beta",
7
+ "cli": "0.4.0-beta"
8
8
  }
@@ -1,3 +1,7 @@
1
1
  import type { CreateOptions } from "./contracts.js";
2
- export declare const usage = "Usage: npm create @nylorun/agent@beta <directory> [--no-studio] [--no-open] [--yes]";
2
+ export declare const usage = "Usage: npm create @nylorun/agent@beta <directory> [--yes]";
3
+ /** Printed when `--no-open` is passed; the flag is accepted and ignored. */
4
+ export declare const NO_OPEN_IGNORED = "--no-open is ignored: the creator no longer starts development, so it opens no browser.";
5
+ /** Printed when `--no-studio` is passed; the flag is accepted and ignored. */
6
+ export declare const NO_STUDIO_DEPRECATED = "--no-studio is deprecated and ignored: Studio runs in the local Docker stack, so generated projects no longer depend on @nylorun/studio. Use --no-open to keep the browser closed.";
3
7
  export declare function parse(argv: readonly string[]): CreateOptions;
package/dist/arguments.js CHANGED
@@ -1,4 +1,8 @@
1
- export const usage = "Usage: npm create @nylorun/agent@beta <directory> [--no-studio] [--no-open] [--yes]";
1
+ export const usage = "Usage: npm create @nylorun/agent@beta <directory> [--yes]";
2
+ /** Printed when `--no-open` is passed; the flag is accepted and ignored. */
3
+ export const NO_OPEN_IGNORED = "--no-open is ignored: the creator no longer starts development, so it opens no browser.";
4
+ /** Printed when `--no-studio` is passed; the flag is accepted and ignored. */
5
+ export const NO_STUDIO_DEPRECATED = "--no-studio is deprecated and ignored: Studio runs in the local Docker stack, so generated projects no longer depend on @nylorun/studio. Use --no-open to keep the browser closed.";
2
6
  export function parse(argv) {
3
7
  const [directory, ...flags] = argv;
4
8
  if (!directory || directory.startsWith("-"))
@@ -7,8 +11,10 @@ export function parse(argv) {
7
11
  throw new Error(usage);
8
12
  return Object.freeze({
9
13
  directory,
10
- studio: !flags.includes("--no-studio"),
11
- open: !flags.includes("--no-open"),
12
14
  yes: flags.includes("--yes"),
15
+ notes: Object.freeze([
16
+ ...(flags.includes("--no-studio") ? [NO_STUDIO_DEPRECATED] : []),
17
+ ...(flags.includes("--no-open") ? [NO_OPEN_IGNORED] : []),
18
+ ]),
13
19
  });
14
20
  }
package/dist/cli.js CHANGED
@@ -6,12 +6,15 @@ import { dirname, join } from "node:path";
6
6
  import { createProject, CreationError } from "./project.js";
7
7
  import { parse, usage } from "./arguments.js";
8
8
  import { CreationCancelled, runCommand } from "./process.js";
9
+ import { checkDocker } from "./docker.js";
9
10
  async function main() {
10
11
  const argv = process.argv.slice(2);
11
12
  if (argv.length === 1 && ["--help", "-h"].includes(argv[0])) {
12
13
  console.log(usage);
13
14
  return;
14
15
  }
16
+ if (process.platform === "win32")
17
+ throw new Error("Nylorun does not run on native Windows. Use WSL2: install Node 24 and Docker (Docker Desktop's WSL integration) inside your WSL distribution and create the project there (https://learn.microsoft.com/windows/wsl/install).");
15
18
  const options = parse(argv);
16
19
  const [major, minor] = process.versions.node.split(".").map(Number);
17
20
  if (!(major > 22 || (major === 22 && minor >= 19)))
@@ -35,6 +38,8 @@ async function main() {
35
38
  remove: async (path) => rm(path, { recursive: true, force: true }),
36
39
  write: async (path, content) => writeFile(path, content),
37
40
  run: (command, args, directory) => runCommand(command, args, directory, controller.signal),
41
+ nodeVersion: process.versions.node,
42
+ checkDocker,
38
43
  };
39
44
  const compatibility = JSON.parse(await readFile(join(dirname(fileURLToPath(import.meta.url)), "compatibility.json"), "utf8"));
40
45
  await createProject(options, compatibility, dependencies);
@@ -1,8 +1,8 @@
1
1
  {
2
- "harness": "0.18.0-beta",
3
- "studio": "0.8.0-beta",
4
- "runtime": "0.9.0-beta",
5
- "agents": "0.5.0-beta",
6
- "core": "0.4.0-beta",
7
- "cli": "0.2.1-beta"
2
+ "harness": "0.19.1-beta",
3
+ "runtime": "0.11.0-beta",
4
+ "agents": "0.7.0-beta",
5
+ "admin": "0.3.0-beta",
6
+ "core": "0.6.0-beta",
7
+ "cli": "0.4.0-beta"
8
8
  }
@@ -3,14 +3,21 @@ export type Compatibility = Readonly<{
3
3
  cli: string;
4
4
  harness: string;
5
5
  agents: string;
6
- studio: string;
6
+ admin: string;
7
7
  runtime: string;
8
8
  }>;
9
9
  export type CreateOptions = Readonly<{
10
10
  directory: string;
11
- studio: boolean;
12
- open: boolean;
13
11
  yes: boolean;
12
+ /** Deprecation notes for accepted-and-ignored flags, printed first. */
13
+ notes?: readonly string[];
14
+ }>;
15
+ /** Docker and Compose v2, which the local stack needs. */
16
+ export type DockerCheck = Readonly<{
17
+ ok: true;
18
+ }> | Readonly<{
19
+ ok: false;
20
+ problem: string;
14
21
  }>;
15
22
  export type Process = Readonly<{
16
23
  status: number | null;
@@ -27,4 +34,8 @@ export type CreatorDependencies = Readonly<{
27
34
  remove: (path: string) => Promise<void>;
28
35
  write: (path: string, content: string) => Promise<void>;
29
36
  run: (command: string, args: readonly string[], directory: string) => Promise<Process>;
37
+ /** `process.versions.node`: the CLI and the application need Node 24 or newer. */
38
+ nodeVersion: string;
39
+ /** Check that Docker's engine answers and Compose v2 is installed. */
40
+ checkDocker: () => Promise<DockerCheck>;
30
41
  }>;
@@ -0,0 +1,6 @@
1
+ import type { DockerCheck } from "./contracts.js";
2
+ /**
3
+ * The local Nylorun stack runs in Docker Compose. Report, never fix: a missing
4
+ * docker command, an engine that does not answer, or Compose older than v2.
5
+ */
6
+ export declare function checkDocker(): Promise<DockerCheck>;
package/dist/docker.js ADDED
@@ -0,0 +1,43 @@
1
+ import { execFile } from "node:child_process";
2
+ const INSTALL = "Install Docker with Compose v2: Docker Desktop (https://docs.docker.com/get-started/get-docker/), OrbStack (https://orbstack.dev) or Colima (https://github.com/abiosoft/colima)";
3
+ function run(args) {
4
+ return new Promise((resolve) => {
5
+ execFile("docker", [...args], { timeout: 15_000, encoding: "utf8" }, (error, stdout, stderr) => {
6
+ const code = error === null
7
+ ? 0
8
+ : typeof error.code === "number"
9
+ ? Number(error.code)
10
+ : 1;
11
+ resolve({
12
+ code,
13
+ stdout: String(stdout),
14
+ stderr: String(stderr),
15
+ missing: error?.code === "ENOENT",
16
+ });
17
+ });
18
+ });
19
+ }
20
+ const firstLine = (text) => text.trim().split(/\r?\n/u)[0] ?? "";
21
+ /**
22
+ * The local Nylorun stack runs in Docker Compose. Report, never fix: a missing
23
+ * docker command, an engine that does not answer, or Compose older than v2.
24
+ */
25
+ export async function checkDocker() {
26
+ const server = await run(["version", "--format", "{{.Server.Version}}"]);
27
+ if (server.missing)
28
+ return { ok: false, problem: `${INSTALL}. The docker command was not found.` };
29
+ if (server.code !== 0)
30
+ return {
31
+ ok: false,
32
+ problem: `Start Docker (Docker Desktop, OrbStack or Colima): its engine is not reachable (${firstLine(server.stderr) || `exit ${server.code}`}).`,
33
+ };
34
+ const compose = await run(["compose", "version", "--short"]);
35
+ if (compose.code !== 0 || !/^v?[2-9]\./u.test(compose.stdout.trim()))
36
+ return {
37
+ ok: false,
38
+ problem: `${INSTALL}. Docker Compose v2 (the "docker compose" plugin) is required; ${compose.code === 0
39
+ ? `found ${compose.stdout.trim()}`
40
+ : firstLine(compose.stderr) || "it is not installed"}.`,
41
+ };
42
+ return { ok: true };
43
+ }
package/dist/process.js CHANGED
@@ -9,34 +9,21 @@ export class CreationCancelled extends Error {
9
9
  this.exitCode = signal === "SIGINT" ? 130 : 143;
10
10
  }
11
11
  }
12
- /**
13
- * Run the npm that launched this creator. `npm create` sets npm_execpath, which
14
- * avoids the Windows `.cmd` shim (Node rejects spawning it without a shell).
15
- * Arguments are fixed literals, so the shell fallback carries no injection risk.
16
- */
12
+ /** Run the npm that launched this creator (`npm create` sets npm_execpath). */
17
13
  function npmInvocation(args) {
18
14
  const execPath = process.env.npm_execpath;
19
15
  if (execPath && /\.[cm]?js$/u.test(execPath))
20
- return {
21
- command: process.execPath,
22
- args: [execPath, ...args],
23
- shell: false,
24
- };
25
- if (process.platform === "win32")
26
- return { command: "npm.cmd", args: [...args], shell: true };
27
- return { command: "npm", args: [...args], shell: false };
16
+ return { command: process.execPath, args: [execPath, ...args] };
17
+ return { command: "npm", args: [...args] };
28
18
  }
29
19
  /** Own npm and its descendants, including authentication started by a script. */
30
20
  export async function runCommand(command, args, directory, signal) {
31
21
  signal.throwIfAborted();
32
- const invocation = command === "npm"
33
- ? npmInvocation(args)
34
- : { command, args: [...args], shell: false };
22
+ const invocation = command === "npm" ? npmInvocation(args) : { command, args: [...args] };
35
23
  const child = spawn(invocation.command, invocation.args, {
36
24
  cwd: directory,
37
25
  stdio: "inherit",
38
- detached: process.platform !== "win32",
39
- shell: invocation.shell,
26
+ detached: true,
40
27
  });
41
28
  let shutdown;
42
29
  const stop = (requested) => {
@@ -68,14 +55,6 @@ export async function runCommand(command, args, directory, signal) {
68
55
  async function stopTree(requested) {
69
56
  if (!child.pid)
70
57
  return;
71
- if (process.platform === "win32") {
72
- await new Promise((resolve) => {
73
- const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
74
- killer.once("error", () => resolve());
75
- killer.once("close", () => resolve());
76
- });
77
- return;
78
- }
79
58
  const send = (value) => {
80
59
  try {
81
60
  process.kill(-child.pid, value);
package/dist/project.js CHANGED
@@ -10,13 +10,15 @@ export class CreationError extends Error {
10
10
  }
11
11
  }
12
12
  export async function createProject(options, compatibility, dependencies) {
13
+ for (const note of options.notes ?? [])
14
+ dependencies.log(note);
13
15
  const currentDirectory = resolve(dependencies.currentDirectory());
14
16
  const destination = resolve(currentDirectory, options.directory);
15
17
  const pathFromCurrentDirectory = relative(currentDirectory, destination);
16
18
  if (isAbsolute(options.directory) ||
17
19
  pathFromCurrentDirectory === "" ||
18
20
  pathFromCurrentDirectory === ".." ||
19
- pathFromCurrentDirectory.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`))
21
+ pathFromCurrentDirectory.startsWith("../"))
20
22
  throw new Error("Target directory must be a new child of the current directory.");
21
23
  if (await dependencies.exists(destination))
22
24
  throw new Error(`Target directory already exists: ${destination}`);
@@ -25,7 +27,7 @@ export async function createProject(options, compatibility, dependencies) {
25
27
  await dependencies.makeDirectory(temporary);
26
28
  try {
27
29
  const files = {
28
- ...(await starterFiles(compatibility, options.studio)),
30
+ ...(await starterFiles(compatibility)),
29
31
  };
30
32
  const name = packageName(basename(destination));
31
33
  const manifest = JSON.parse(files["package.json"]);
@@ -46,12 +48,13 @@ export async function createProject(options, compatibility, dependencies) {
46
48
  }
47
49
  dependencies.log("Installing dependencies...");
48
50
  await stage("Installation", ["install", ...(options.yes ? ["--yes"] : [])]);
49
- dependencies.log("Starting development. The first start sets up the model provider in the Runtime vault.");
50
- await stage("Development", [
51
- "run",
52
- "dev",
53
- ...(options.open ? [] : ["--", "--no-open"]),
54
- ]);
51
+ const next = nextSteps(destination);
52
+ const missing = await missingPrerequisites(dependencies);
53
+ if (missing.length)
54
+ throw new CreationError(`Project created. Before starting it, set up the prerequisites:\n${missing
55
+ .map((line) => ` ${line}`)
56
+ .join("\n")}\nThen run:\n${next}`);
57
+ dependencies.log(`Project created. Next:\n${next}`);
55
58
  async function stage(name, args) {
56
59
  try {
57
60
  dependencies.signal?.throwIfAborted();
@@ -66,15 +69,40 @@ export async function createProject(options, compatibility, dependencies) {
66
69
  }
67
70
  catch (error) {
68
71
  const cancelled = error instanceof CreationCancelled;
69
- const recovery = [
70
- `cd ${quote(destination)}`,
71
- ...(name === "Installation" ? ["npm install"] : []),
72
- "npm run dev",
73
- ].join("\n");
74
- throw new CreationError(`${cancelled ? error.message : `${name} failed.`} The generated project was kept.\n${name === "Development" ? "Restart" : "Resume"} with:\n${recovery}`, cancelled ? error.exitCode : 1);
72
+ throw new CreationError(`${cancelled ? error.message : `${name} failed.`} The generated project was kept.\nResume with:\ncd ${quote(destination)}\nnpm install\n${NEXT.join("\n")}`, cancelled ? error.exitCode : 1);
75
73
  }
76
74
  }
77
75
  }
76
+ /**
77
+ * After creation: start the local stack (nylorun), create and link the
78
+ * Project's Tenant (the Runtime client, @nylorun/cli), then develop. The
79
+ * creator runs none of them; the project itself depends only on
80
+ * @nylorun/agents.
81
+ */
82
+ const NEXT = [
83
+ "npx nylorun@beta up # the local Runtime and Studio (Docker)",
84
+ "npx @nylorun/cli@beta tenant create # this project's Tenant, linked in .nylorun/",
85
+ "npm run dev",
86
+ ];
87
+ function nextSteps(destination) {
88
+ return [`cd ${quote(destination)}`, ...NEXT].join("\n");
89
+ }
90
+ /** The CLI and the generated application need Node 24 APIs. */
91
+ const MIN_NODE_MAJOR = 24;
92
+ /**
93
+ * Prerequisites the developer installs before `npm run dev`: Node 24 and
94
+ * Docker with Compose v2 (the local stack). The creator only reports them; it
95
+ * never downloads or starts anything.
96
+ */
97
+ async function missingPrerequisites(dependencies) {
98
+ const missing = [];
99
+ if (!(Number(dependencies.nodeVersion.split(".")[0]) >= MIN_NODE_MAJOR))
100
+ missing.push(`Node.js ${MIN_NODE_MAJOR} or newer (found ${dependencies.nodeVersion})`);
101
+ const docker = await dependencies.checkDocker();
102
+ if (!docker.ok)
103
+ missing.push(docker.problem);
104
+ return missing;
105
+ }
78
106
  function packageName(directory) {
79
107
  const name = directory
80
108
  .toLowerCase()
@@ -86,7 +114,5 @@ function packageName(directory) {
86
114
  function quote(value) {
87
115
  if (/^[a-zA-Z0-9_./-]+$/.test(value))
88
116
  return value;
89
- return process.platform === "win32"
90
- ? `"${value.replaceAll('"', '""')}"`
91
- : `'${value.replaceAll("'", "'\\''")}'`;
117
+ return `'${value.replaceAll("'", "'\\''")}'`;
92
118
  }
@@ -1,2 +1,2 @@
1
1
  import type { Compatibility } from "./contracts.js";
2
- export declare function starterFiles(compatibility: Compatibility, studio: boolean): Promise<Readonly<Record<string, string>>>;
2
+ export declare function starterFiles(compatibility: Compatibility): Promise<Readonly<Record<string, string>>>;
package/dist/scaffold.js CHANGED
@@ -12,7 +12,7 @@ function templatePath(path) {
12
12
  .map((segment) => (segment === "_gitignore" ? ".gitignore" : segment))
13
13
  .join("/");
14
14
  }
15
- export async function starterFiles(compatibility, studio) {
15
+ export async function starterFiles(compatibility) {
16
16
  const root = fileURLToPath(new URL("./starter/", import.meta.url));
17
17
  const files = {};
18
18
  async function walk(directory) {
@@ -23,22 +23,14 @@ export async function starterFiles(compatibility, studio) {
23
23
  else
24
24
  files[templatePath(relative(root, absolute))] = (await readFile(absolute, "utf8"))
25
25
  .replaceAll("{{CORE_VERSION}}", compatibility.core)
26
- .replaceAll("{{CLI_VERSION}}", compatibility.cli)
27
26
  .replaceAll("{{HARNESS_VERSION}}", compatibility.harness)
28
27
  .replaceAll("{{AGENTS_VERSION}}", compatibility.agents)
29
- .replaceAll("{{RUNTIME_VERSION}}", compatibility.runtime)
30
- .replaceAll("{{STUDIO_VERSION}}", compatibility.studio);
28
+ .replaceAll("{{ADMIN_VERSION}}", compatibility.admin)
29
+ .replaceAll("{{RUNTIME_VERSION}}", compatibility.runtime);
31
30
  }
32
31
  }
33
32
  await walk(root);
34
33
  if (!("." + "gitignore" in files))
35
34
  throw new Error("Starter template is missing its .gitignore.");
36
- if (!studio) {
37
- const manifest = JSON.parse(files["package.json"]);
38
- delete manifest.devDependencies["@nylorun/studio"];
39
- manifest.scripts.dev = "nylorun dev --no-studio";
40
- delete manifest.scripts.studio;
41
- files["package.json"] = JSON.stringify(manifest, null, 2) + "\n";
42
- }
43
35
  return Object.freeze(files);
44
36
  }
@@ -1,5 +1,6 @@
1
- # Model provider credentials are stored in the Runtime vault (.nylorun/), not here.
2
- # The first nylorun dev / nylorun serve prompts for them, or seeds them once from:
1
+ # Read by `npm run dev` (tsx --env-file-if-exists=.env) and, once, by
2
+ # `npx @nylorun/cli tenant create`, which seeds the Tenant's model provider
3
+ # from these into the Runtime vault (never back into this file):
3
4
  # MODEL_PROVIDER=...
4
5
  # MODEL=...
5
6
  # MODEL_PROVIDER_API_KEY=...
@@ -1,22 +1,90 @@
1
1
  # My Nylorun agent
2
2
 
3
- Requires Node 24 and npm 11. Agent and tool definitions live in `agents/`. A separate SQLite Runtime holds your sessions; this project attaches to it and connects your tools through the SDK's authenticated SSE executor.
3
+ Before you start, install the prerequisites once. Nothing downloads them for
4
+ you; `npx nylorun@beta doctor` checks them.
5
+
6
+ - Node 24 or newer.
7
+ - Docker with Compose v2: [Docker
8
+ Desktop](https://docs.docker.com/get-started/get-docker/),
9
+ [OrbStack](https://orbstack.dev) or [Colima](https://github.com/abiosoft/colima).
10
+ The local Runtime and Studio run as a Docker Compose stack.
11
+
12
+ On Windows, use [WSL2](https://learn.microsoft.com/windows/wsl/install): install
13
+ Node inside your WSL distribution, enable Docker Desktop's WSL integration, and
14
+ keep the project in the Linux filesystem (`~/…`, not `/mnt/c/…`), where file
15
+ watching works.
16
+
17
+ Agent and tool definitions live in `agents/`. The **Runtime** holds your
18
+ sessions in isolated **Tenants**; this project attaches through a **Project
19
+ link** and connects your tools through the SDK's authenticated SSE executor.
20
+ Production entry is `src/main.ts`, which calls `connectAgents`. The project
21
+ depends only on `@nylorun/agents`; the two Nylorun tools run with `npx`:
22
+
23
+ - `nylorun` sets up and runs the local stack (Runtime and Studio).
24
+ - `@nylorun/cli` (command `nylo`) talks to a Runtime: Tenants, the Project
25
+ link and the model provider.
4
26
 
5
27
  ```sh
28
+ npx nylorun@beta up # the local stack; the first run pulls the images
29
+ npx @nylorun/cli@beta tenant create # this project's Tenant, linked in .nylorun/
6
30
  npm run dev
7
31
  ```
8
32
 
9
- The first run starts the Runtime for you and asks for a model provider, storing the credential in the Runtime vault. **The Runtime keeps running after you stop `dev`, so sessions survive a source change.** `npx nylorun down` stops it; `npx nylorun runtime status` shows where it is. Later runs reuse it. Open Studio and ask **Look up order demo-123**. The local tool returns `shipped`; Studio shows the tool call and assistant response. Model calls use the Runtime's saved provider and may incur its usual charges. Studio's Model provider screen can replace an API key. `npx nylorun configure` does the same from a terminal while the Runtime is running.
33
+ `nylorun up` sets up the stack under `~/.nylorun` on the first run and just
34
+ starts it after that. It prints the Runtime URL and a Studio login URL. The
35
+ stack keeps running after you stop `npm run dev`, so sessions survive a source
36
+ change; `npx nylorun down` stops it (volumes are kept), `npx nylorun status`
37
+ shows its health, and `npx nylorun logs runtime -f` its logs.
38
+
39
+ `tenant create` creates this project's Tenant, writes `.nylorun/link.json` and
40
+ `.nylorun/credentials.json`, and seeds the Tenant's model provider from
41
+ `MODEL_PROVIDER`, `MODEL` and `MODEL_PROVIDER_API_KEY` in `.env` (see
42
+ `.env.example`). The key is stored in the Tenant vault, never back in `.env`.
43
+ Without them, set the provider in Studio's Model provider screen, or with
44
+ `npx @nylorun/cli configure`. Model calls use the Tenant's provider and may
45
+ incur its usual charges.
10
46
 
11
- `npm run dev -- --no-open` avoids opening a browser. `--no-studio` runs headless. `--no-autostart` fails instead of starting a Runtime, which is what CI wants. Use `npm run studio` to attach separately. Runtime defaults to `http://127.0.0.1:8787`; `--port` or `PORT` changes it. Studio chooses a free port starting at 4161.
47
+ `npm run dev` runs `src/main.ts` with `tsx watch`; `connectAgents` finds the
48
+ Runtime through the Project link. `npx nylorun studio` opens a fresh Studio
49
+ login on this project's Tenant (a login URL works once, for two minutes). In
50
+ Studio, ask **Look up order demo-123**. The local tool returns `shipped`;
51
+ Studio shows the tool call and assistant response. The Runtime listens on
52
+ `http://localhost:8787` and Studio on `http://localhost:4161`, or on free ports
53
+ chosen on the first start.
12
54
 
13
55
  ```sh
14
56
  npm run build
15
57
  npm start
16
58
  ```
17
59
 
18
- `npm start` runs `nylorun serve`, which attaches the compiled build without Studio or watching, starting the Runtime first if none is up. Studio can attach in a separate terminal. `agents/index.ts` exports the registry; there is no Hono app to maintain. A source edit re-registers agents and reconnects executors; the Runtime process is untouched. Start a new session after changing definitions or implementations; active-session upgrades are not supported.
60
+ `npm start` runs `node dist/src/main.js`, the same `connectAgents` entry as
61
+ development. Set `NYLORUN_RUNTIME_URL`, `NYLORUN_TENANT`, and
62
+ `NYLORUN_SERVER_KEY` before starting, or keep the Project link beside this
63
+ directory. `agents/index.ts` exports the registry. A source edit re-registers
64
+ agents and reconnects executors; the Runtime is untouched. Start a new session
65
+ after changing definitions or implementations; active-session upgrades are not
66
+ supported.
67
+
68
+ Export the linked Project environment:
69
+
70
+ ```sh
71
+ eval "$(npx @nylorun/cli@beta env)"
72
+ # → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY, NYLORUN_TENANT
73
+ ```
19
74
 
20
- Local Runtime credentials, the model provider vault, SQLite, and the Runtime log live in gitignored `.nylorun/` beside this project. Each project gets its own Runtime; `nylorun up --global` shares one in `~/.nylorun` instead. Keep this directory private. Server and executor credentials are generated automatically. The model provider key is encrypted in the vault and kept out of browser configuration and `.env`. Ordinary shutdown/restart preserves completed session history. `NYLORUN_IMPLEMENTATION_VERSION` defaults to `dev`; assign an explicit version when changing a versioned implementation.
75
+ Project link and credentials live in gitignored `.nylorun/` beside this project.
76
+ The Host root (`NYLORUN_HOME` or `~/.nylorun`) holds the stack's files and the
77
+ admin key; Tenant data lives in the stack's Docker volumes. A fresh clone or
78
+ second worktree does not reuse this link: run `tenant create` there, or
79
+ `npx @nylorun/cli tenant use <name>` with that Tenant's credentials.
80
+ Keep `.nylorun/` private. Application credentials are generated when the
81
+ Tenant is created; executor tokens are derived at start. Ordinary
82
+ shutdown/restart preserves completed session history; `npx nylorun reset`
83
+ deletes every Tenant.
84
+ `NYLORUN_IMPLEMENTATION_VERSION` defaults to `dev`; assign an explicit version
85
+ when changing a versioned implementation.
21
86
 
22
- This beta supports local text and ordinary tools. Advanced waits, media, MCP, deployment, reconciliation and broad recovery guarantees are deferred. Subagents are supported in the SDK and examples (`agents used as tools`); the starter itself does not wire them. `NYLORUN_DEV_MODEL=fixture` is a credential-free release-check fixture for this starter; it is not a general model.
87
+ This beta supports local text and ordinary tools. Advanced waits, media, MCP,
88
+ deployment, reconciliation and broad recovery guarantees are deferred.
89
+ Subagents are supported in the SDK and examples (`agents used as tools`); the
90
+ starter itself does not wire them.
@@ -7,21 +7,18 @@
7
7
  "node": ">=24.0.0"
8
8
  },
9
9
  "scripts": {
10
- "dev": "nylorun dev",
11
- "studio": "nylorun studio",
10
+ "dev": "tsx watch --env-file-if-exists=.env src/main.ts",
12
11
  "build": "node -e \"import('node:fs/promises').then(async ({rm,cp}) => { await rm('dist', { recursive: true, force: true }); await cp('agents', 'dist/agents', { recursive: true, filter: (source) => !source.endsWith('.ts') }); })\" && tsc -p tsconfig.json",
13
- "start": "nylorun serve",
12
+ "start": "node dist/src/main.js",
14
13
  "check": "tsc --noEmit"
15
14
  },
16
15
  "dependencies": {
17
16
  "zod": "^4.6.5",
18
- "@nylorun/agents": "{{AGENTS_VERSION}}",
19
- "@nylorun/cli": "{{CLI_VERSION}}"
17
+ "@nylorun/agents": "{{AGENTS_VERSION}}"
20
18
  },
21
19
  "devDependencies": {
22
- "@nylorun/studio": "{{STUDIO_VERSION}}",
23
20
  "@types/node": "^22.18.0",
24
- "tsx": "^4.20.6",
21
+ "tsx": "^4.23.15",
25
22
  "typescript": "^7.0.2"
26
23
  }
27
24
  }
@@ -0,0 +1,4 @@
1
+ import { connectAgents } from "@nylorun/agents";
2
+ import { agents } from "../agents/index.js";
3
+
4
+ await connectAgents({ agents }).ready;
package/dist/sync.js CHANGED
@@ -3,7 +3,7 @@ import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
3
3
  import { dirname, join, resolve } from "node:path";
4
4
  import { starterFiles } from "./scaffold.js";
5
5
  export async function examplesFiles(compatibility, recipe) {
6
- const rendered = await starterFiles(compatibility, true);
6
+ const rendered = await starterFiles(compatibility);
7
7
  const files = Object.fromEntries(Object.entries(rendered).filter(([path]) => managed(path)));
8
8
  const manifest = JSON.parse(files["package.json"]);
9
9
  manifest.name = recipe.name;
@@ -14,7 +14,6 @@ export async function examplesFiles(compatibility, recipe) {
14
14
  "configure",
15
15
  "dev",
16
16
  "inspect",
17
- "studio",
18
17
  "build",
19
18
  "start",
20
19
  "check",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nylorun/create-agent",
3
- "version": "0.8.1-beta",
3
+ "version": "0.10.0-beta",
4
4
  "description": "Create a local Nylorun Harness agent project.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",