NylorunDocsBeta
Get started

Your project

The generated tree, how it saves your agents, and where state lives.

npm create @nylorun/agent@beta writes a TypeScript app. It starts nothing and writes no .nylorun/ — nylorun start does that.

my-agent/
  agents/
    assistant/agent.ts
    index.ts
  runtime/
    scratch.runtime.json
  src/main.ts
  package.json
  tsconfig.json
  README.md
  .env.example
  .gitignore

After nylorun start:

  .nylorun/
    link.json
    credentials.json
src/main.ts
import { readFile } from "node:fs/promises";
import { createClient } from "@nylorun/agents";
import { agents } from "../agents/index.js";

const client = await createClient();
const { $schema: _, ...runtime } = JSON.parse(
  await readFile(new URL("../runtime/scratch.runtime.json", import.meta.url), "utf8"),
);
for (const agent of agents) {
  const { manifest } = await client.agentManifests.save({ agent, runtime });
  const made = await client.agents.put(agent.id, { manifest: agent.id });
  console.log(`Saved agent ${agent.id} v${manifest.version} (Agent ${made.id} runs v${made.resolvedVersion})`);
}

This process saves each agent in agents/index.ts to the Runtime as an agent manifest, with the runtime section in runtime/scratch.runtime.json: a virtual workspace with no network, checked by the schema its $schema names (https://docs.nylorun.com/schemas/runtime-manifest/v1.json). It then makes the Agent the agent's sessions run on, named after the agent, and exits. It runs no server: the Runtime runs the agents from their manifests, and no code of the project runs during a session.

The Agent tracks its manifest. Each save moves it to the new version in place, with its disk, secrets, and sessions, and each session's next turn runs the edit; a turn already running ends on its version. To keep the Agent on one version, pin it: npx nylorun agents pin assistant <version>.

The starter's assistant has no tools; a comment in agents/assistant/agent.ts shows how to add an HTTP tool. A code tool (tool({ run })) is refused when it is saved.

An agent can also be written as an agent manifest, an AGENT.md with optional JSON files, or a flow of agents (flow.json), with no TypeScript. nylorun writes, checks, and saves one, and talks to its Agent:

npx nylorun init agents/hello --example
npx nylorun check agents/hello
npx nylorun apply agents/hello --agent
npx nylorun chat hello

init <path> names the agent after the path's last segment, and --example adds an HTTP tool, an MCP server, and a trigger, each explained in its README.md. apply --agent saves the folder and makes the Agent hello from it, or moves it to the new version.

Scripts

ScriptCommandRole
devtsx watch --env-file-if-exists=.env src/main.tsSave the agents and make their Agents, and again on every source edit.
buildcopy the agents assets and runtime/, and run tscProduce dist/.
startnode dist/src/main.jsSave the agents and make their Agents once, as a deploy step.
checktsc --noEmitTypecheck.

Production dependencies are @nylorun/agents and zod. The project does not install the CLI, Studio, or Runtime; run them with npx.

Where state lives

LocationContentsCommit?
Project .nylorun/Tenant link, application key, and management key.No
~/.nylorun/tenants/<name>/Tenant files, Docker compose, vault key. NYLORUN_HOME replaces the directory.No
Docker volumesPostgres, Restate, s2-lite, object store, workspaces.No
.envOne-time model seed.No

Deleting .nylorun/ unlinks the project without deleting the Tenant. Run npx nylorun start --tenant <name> to attach again.

Outside this machine, set NYLORUN_RUNTIME_URL and NYLORUN_SERVER_KEY instead of relying on the link. See Docker Compose.

Next step

On this page