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
.gitignoreAfter nylorun start:
.nylorun/
link.json
credentials.jsonimport { 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 helloinit <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
| Script | Command | Role |
|---|---|---|
dev | tsx watch --env-file-if-exists=.env src/main.ts | Save the agents and make their Agents, and again on every source edit. |
build | copy the agents assets and runtime/, and run tsc | Produce dist/. |
start | node dist/src/main.js | Save the agents and make their Agents once, as a deploy step. |
check | tsc --noEmit | Typecheck. |
Production dependencies are @nylorun/agents and zod. The project does not
install the CLI, Studio, or Runtime; run them with npx.
Where state lives
| Location | Contents | Commit? |
|---|---|---|
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 volumes | Postgres, Restate, s2-lite, object store, workspaces. | No |
.env | One-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.