@nylorun/create-agent 0.9.0-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,33 @@
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
+
3
31
  ## 0.9.0-beta
4
32
 
5
33
  ### Minor Changes
package/README.md CHANGED
@@ -1,59 +1,70 @@
1
1
  # @nylorun/create-agent
2
2
 
3
3
  Install the prerequisites first (the creator checks them and never installs
4
- them):
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.
5
11
 
6
12
  ```sh
7
- node --version # 24 or newer
8
- npm install --global @nylorun/runtime@beta # provides nylorun-runtime
13
+ node --version # 24 or newer
14
+ docker compose version # v2
9
15
  npm create @nylorun/agent@beta my-agent
10
16
  ```
11
17
 
12
- Creates a Node 24 project with `@nylorun/agents` and Zod in production, plus
13
- `@nylorun/cli` and optional Studio as development tools. The registry in
14
- `agents/index.ts` exports agent definitions. `src/main.ts` calls
15
- `connectAgents` for both `npm run dev` and `npm start`. The starter includes
16
- 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”.
17
23
 
18
- Creation installs dependencies and starts development. If a prerequisite is
19
- missing, it stops after creating the project and prints what to install. Use `-- --no-studio` to
20
- omit Studio from the project, or `-- --no-open` to suppress browser opening.
21
- `--yes` affects installation only. The first `nylorun dev` starts the local
22
- Runtime and asks for the model provider when the terminal is interactive and
23
- stores the credential in the Runtime vault. A non-interactive start without a
24
- 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.
25
29
 
26
30
  ```sh
27
31
  cd my-agent
28
- npm run dev
29
- npm run studio
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
30
36
  npm run build
31
37
  npm start
32
38
  ```
33
39
 
34
- `npm run studio` runs `nylorun-studio` and can start before or after `dev`.
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.
35
46
  `npm start` runs `node dist/src/main.js` with the same entry as development.
36
- Export the Project environment (`eval "$(npx nylorun runtime status --env)"`)
37
- before a production start when there is no Project link. Studio can replace an
38
- API-key credential. `nylorun configure` replaces the credential against an
39
- already running Runtime. Local Runtime credentials, the vault, and SQLite are
40
- stored in gitignored `.nylorun/`. Definitions have no model provider or
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
41
50
  `agent.run()`.
42
51
 
43
52
  `starter/` is the canonical template. `compatibility.json` pins core, harness,
44
- agents, admin, Runtime, Studio and CLI. The examples recipe adds local package
45
- dependencies. Run `npm run examples:sync` after template changes, then
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
46
56
  `npm install --prefix examples`. Sync preserves authored agents, tests,
47
57
  credentials, and local state; it rejects conflicting edits to generated files.
48
58
 
49
59
  The default examples registry contains the release starter. Advanced examples
50
60
  remain outside that registry for later migration.
51
61
 
52
- After building, `node create-agent/scripts/smoke-starter.mjs` installs packed
53
- packages outside the workspace and checks the actual Studio/tool workflow,
54
- history, reload, source restart, compiled start, headless mode, and shutdown.
55
- It uses a deterministic fixture without live provider calls. Browser checks
56
- 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.
57
68
 
58
69
  See [RELEASING](../RELEASING.md) for the Changesets beta workflow. Nothing is
59
70
  published by the smoke check.
@@ -1,9 +1,8 @@
1
1
  {
2
- "harness": "0.19.0-beta",
3
- "studio": "0.9.0-beta",
4
- "runtime": "0.10.0-beta",
5
- "agents": "0.6.0-beta",
6
- "admin": "0.2.0-beta",
7
- "core": "0.5.0-beta",
8
- "cli": "0.3.0-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"
9
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
@@ -1,34 +1,20 @@
1
1
  #!/usr/bin/env node
2
2
  import { mkdir, rename, rm, writeFile, readFile } from "node:fs/promises";
3
- import { existsSync, statSync } from "node:fs";
3
+ import { existsSync } from "node:fs";
4
4
  import { fileURLToPath } from "node:url";
5
- import { delimiter, dirname, join } from "node:path";
5
+ 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
- function findOnPath(name) {
10
- const extensions = process.platform === "win32"
11
- ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
12
- : [""];
13
- for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean))
14
- for (const extension of extensions) {
15
- const candidate = join(dir, `${name}${extension.toLowerCase()}`);
16
- try {
17
- if (statSync(candidate).isFile())
18
- return candidate;
19
- }
20
- catch {
21
- /* not here */
22
- }
23
- }
24
- return undefined;
25
- }
9
+ import { checkDocker } from "./docker.js";
26
10
  async function main() {
27
11
  const argv = process.argv.slice(2);
28
12
  if (argv.length === 1 && ["--help", "-h"].includes(argv[0])) {
29
13
  console.log(usage);
30
14
  return;
31
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).");
32
18
  const options = parse(argv);
33
19
  const [major, minor] = process.versions.node.split(".").map(Number);
34
20
  if (!(major > 22 || (major === 22 && minor >= 19)))
@@ -53,7 +39,7 @@ async function main() {
53
39
  write: async (path, content) => writeFile(path, content),
54
40
  run: (command, args, directory) => runCommand(command, args, directory, controller.signal),
55
41
  nodeVersion: process.versions.node,
56
- findOnPath,
42
+ checkDocker,
57
43
  };
58
44
  const compatibility = JSON.parse(await readFile(join(dirname(fileURLToPath(import.meta.url)), "compatibility.json"), "utf8"));
59
45
  await createProject(options, compatibility, dependencies);
@@ -1,9 +1,8 @@
1
1
  {
2
- "harness": "0.19.0-beta",
3
- "studio": "0.9.0-beta",
4
- "runtime": "0.10.0-beta",
5
- "agents": "0.6.0-beta",
6
- "admin": "0.2.0-beta",
7
- "core": "0.5.0-beta",
8
- "cli": "0.3.0-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"
9
8
  }
@@ -4,14 +4,20 @@ export type Compatibility = Readonly<{
4
4
  harness: string;
5
5
  agents: string;
6
6
  admin: string;
7
- studio: string;
8
7
  runtime: string;
9
8
  }>;
10
9
  export type CreateOptions = Readonly<{
11
10
  directory: string;
12
- studio: boolean;
13
- open: boolean;
14
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;
15
21
  }>;
16
22
  export type Process = Readonly<{
17
23
  status: number | null;
@@ -28,8 +34,8 @@ export type CreatorDependencies = Readonly<{
28
34
  remove: (path: string) => Promise<void>;
29
35
  write: (path: string, content: string) => Promise<void>;
30
36
  run: (command: string, args: readonly string[], directory: string) => Promise<Process>;
31
- /** `process.versions.node`: the Runtime needs Node 24 or newer. */
37
+ /** `process.versions.node`: the CLI and the application need Node 24 or newer. */
32
38
  nodeVersion: string;
33
- /** Path of `name` on PATH, or undefined (finds `nylorun-runtime`). */
34
- findOnPath: (name: string) => string | undefined;
39
+ /** Check that Docker's engine answers and Compose v2 is installed. */
40
+ checkDocker: () => Promise<DockerCheck>;
35
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,17 +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
- const missing = missingPrerequisites(dependencies, compatibility.runtime);
51
+ const next = nextSteps(destination);
52
+ const missing = await missingPrerequisites(dependencies);
50
53
  if (missing.length)
51
- throw new CreationError(`Project created. Before starting it, install the prerequisites:\n${missing
54
+ throw new CreationError(`Project created. Before starting it, set up the prerequisites:\n${missing
52
55
  .map((line) => ` ${line}`)
53
- .join("\n")}\nThen run:\ncd ${quote(destination)}\nnpm run dev`);
54
- dependencies.log("Starting development. The first start sets up the model provider in the Runtime vault.");
55
- await stage("Development", [
56
- "run",
57
- "dev",
58
- ...(options.open ? [] : ["--", "--no-open"]),
59
- ]);
56
+ .join("\n")}\nThen run:\n${next}`);
57
+ dependencies.log(`Project created. Next:\n${next}`);
60
58
  async function stage(name, args) {
61
59
  try {
62
60
  dependencies.signal?.throwIfAborted();
@@ -71,27 +69,38 @@ export async function createProject(options, compatibility, dependencies) {
71
69
  }
72
70
  catch (error) {
73
71
  const cancelled = error instanceof CreationCancelled;
74
- const recovery = [
75
- `cd ${quote(destination)}`,
76
- ...(name === "Installation" ? ["npm install"] : []),
77
- "npm run dev",
78
- ].join("\n");
79
- 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);
80
73
  }
81
74
  }
82
75
  }
83
- /** The Runtime needs node:sqlite and Node 24 APIs. */
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. */
84
91
  const MIN_NODE_MAJOR = 24;
85
92
  /**
86
- * Prerequisites the developer installs before running the Runtime. The
87
- * creator only reports them; it never downloads Node or the Runtime.
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.
88
96
  */
89
- function missingPrerequisites(dependencies, runtimeVersion) {
97
+ async function missingPrerequisites(dependencies) {
90
98
  const missing = [];
91
99
  if (!(Number(dependencies.nodeVersion.split(".")[0]) >= MIN_NODE_MAJOR))
92
100
  missing.push(`Node.js ${MIN_NODE_MAJOR} or newer (found ${dependencies.nodeVersion})`);
93
- if (!dependencies.findOnPath("nylorun-runtime"))
94
- missing.push(`npm install --global @nylorun/runtime@${runtimeVersion}`);
101
+ const docker = await dependencies.checkDocker();
102
+ if (!docker.ok)
103
+ missing.push(docker.problem);
95
104
  return missing;
96
105
  }
97
106
  function packageName(directory) {
@@ -105,7 +114,5 @@ function packageName(directory) {
105
114
  function quote(value) {
106
115
  if (/^[a-zA-Z0-9_./-]+$/.test(value))
107
116
  return value;
108
- return process.platform === "win32"
109
- ? `"${value.replaceAll('"', '""')}"`
110
- : `'${value.replaceAll("'", "'\\''")}'`;
117
+ return `'${value.replaceAll("'", "'\\''")}'`;
111
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
28
  .replaceAll("{{ADMIN_VERSION}}", compatibility.admin)
30
- .replaceAll("{{RUNTIME_VERSION}}", compatibility.runtime)
31
- .replaceAll("{{STUDIO_VERSION}}", compatibility.studio);
29
+ .replaceAll("{{RUNTIME_VERSION}}", compatibility.runtime);
32
30
  }
33
31
  }
34
32
  await walk(root);
35
33
  if (!("." + "gitignore" in files))
36
34
  throw new Error("Starter template is missing its .gitignore.");
37
- if (!studio) {
38
- const manifest = JSON.parse(files["package.json"]);
39
- delete manifest.devDependencies["@nylorun/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 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,75 +1,90 @@
1
1
  # My Nylorun agent
2
2
 
3
3
  Before you start, install the prerequisites once. Nothing downloads them for
4
- you; `npx nylorun doctor runtime` checks both.
4
+ you; `npx nylorun@beta doctor` checks them.
5
5
 
6
- ```sh
7
- node --version # 24 or newer
8
- npm install --global @nylorun/runtime # the Runtime (nylorun-runtime)
9
- ```
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.
10
16
 
11
- Agent and tool definitions live in `agents/`. A
12
- **Runtime Host** holds your sessions in isolated **Tenants**; this project
13
- attaches through a **Project link** and connects your tools through the SDK's
14
- authenticated SSE executor. Production entry is `src/main.ts`, which calls
15
- `connectAgents`.
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.
16
26
 
17
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/
18
30
  npm run dev
19
31
  ```
20
32
 
21
- The first run starts (or attaches to) the Runtime Host, creates a Tenant,
22
- writes `.nylorun/link.json` and `.nylorun/credentials.json`, and asks for a
23
- model provider (stored in that Tenant's vault). **The Host keeps running after
24
- you stop `dev`, so sessions survive a source change.** `npx nylorun runtime down`
25
- stops it; `npx nylorun runtime status` shows Host and Tenants. Later runs reuse
26
- the link. Open Studio and ask **Look up order demo-123**. The local tool returns
27
- `shipped`; Studio shows the tool call and assistant response. Model calls use
28
- the Tenant's saved provider and may incur its usual charges. Studio's Model
29
- provider screen can replace an API key. `npx nylorun configure` does the same
30
- from a terminal while the Host 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.
31
46
 
32
- `npm run dev -- --no-open` avoids opening a browser. `--no-autostart` fails
33
- instead of starting a Host, which is what CI wants. `npm run dev -- --ephemeral`
34
- uses a private temporary Host and one Tenant (removed on clean exit). Use
35
- `npm run studio` (`nylorun-studio`) to attach separately — before or after
36
- `dev`. Host defaults to loopback port `8787`; `--port` changes it when starting.
37
- 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.
38
54
 
39
55
  ```sh
40
56
  npm run build
41
57
  npm start
42
58
  ```
43
59
 
44
- `npm start` runs `node dist/src/main.js` — the same `connectAgents` entry as
60
+ `npm start` runs `node dist/src/main.js`, the same `connectAgents` entry as
45
61
  development. Set `NYLORUN_RUNTIME_URL`, `NYLORUN_TENANT`, and
46
- `NYLORUN_SERVER_KEY` (for example `eval "$(npx nylorun runtime status --env)"`)
47
- before starting, or keep the Project link beside this directory. Studio can
48
- attach in a separate terminal. `agents/index.ts` exports the registry. A source
49
- edit re-registers agents and reconnects executors; the Host process is
50
- untouched. Start a new session after changing definitions or implementations;
51
- active-session upgrades are not supported.
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.
52
67
 
53
68
  Export the linked Project environment:
54
69
 
55
70
  ```sh
56
- eval "$(npx nylorun runtime status --env)"
71
+ eval "$(npx @nylorun/cli@beta env)"
57
72
  # → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY, NYLORUN_TENANT
58
73
  ```
59
74
 
60
75
  Project link and credentials live in gitignored `.nylorun/` beside this project.
61
- The Host root (`NYLORUN_HOME` or `~/.nylorun`) holds every Tenant. A fresh clone
62
- or second worktree does not reuse this link until you create or choose one.
63
- Keep `.nylorun/` private. Application credentials are generated automatically;
64
- executor tokens are derived at start. The model provider key is encrypted in the
65
- Tenant vault and kept out of browser configuration and `.env`. Ordinary
66
- shutdown/restart preserves completed session history.
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.
67
84
  `NYLORUN_IMPLEMENTATION_VERSION` defaults to `dev`; assign an explicit version
68
85
  when changing a versioned implementation.
69
86
 
70
87
  This beta supports local text and ordinary tools. Advanced waits, media, MCP,
71
88
  deployment, reconciliation and broad recovery guarantees are deferred.
72
89
  Subagents are supported in the SDK and examples (`agents used as tools`); the
73
- starter itself does not wire them. `NYLORUN_DEV_MODEL=fixture` is a
74
- credential-free release-check fixture for this starter; it is not a general
75
- model.
90
+ starter itself does not wire them.
@@ -7,8 +7,7 @@
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
12
  "start": "node dist/src/main.js",
14
13
  "check": "tsc --noEmit"
@@ -18,10 +17,8 @@
18
17
  "@nylorun/agents": "{{AGENTS_VERSION}}"
19
18
  },
20
19
  "devDependencies": {
21
- "@nylorun/cli": "{{CLI_VERSION}}",
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
  }
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.9.0-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",