NylorunDocsBeta
RunConfigure

Local Tenants

Start, stop, and inspect one Nylorun installation per project.

npx nylorun start

In a project, the first start creates the Tenant, writes the project link, seeds the model from .env, starts the containers, and prints the Runtime and Studio URLs. Later starts reuse that Tenant.

CommandWhat it does
start (alias up)Create on first run, start containers, print the URLs.
stop (alias down)Stop containers. Volumes stay. --all stops every Tenant.
status [--json]Tenant, services, endpoints, and Runtime health.
studio [--no-open]Open Studio.
doctor [--json]Node, Docker, Compose v2, and Tenant health.
local logs [service] [-f] [--tail n]Container logs.
local ls [--json]Tenants on this machine.
local reset [--yes]Delete this Tenant's data. The next start creates a new Tenant.
local delete <tenant> --yesRemove containers, volumes, files, and the vault key.
local telemetry status|enable|disableStudio page-view analytics.
tenant reset [--sessions|--agents|--all]Clear sessions, Agents with their secrets, disks, and sessions, or all data. The Tenant and its keys stay.
tenant keys put <id> [--management]Create or rotate a key; prints it once.
tenant keys list [--json] / tenant keys rm <id>List keys with their role, or delete one.
tenant mcp inspect <url> [--agent <id>] [--json]List a remote MCP server's tools, with Agent <id>'s credential for the URL.
agents list [--json] / agents rm <id>List the Tenant's Agents, or delete one.

Every command is on the CLI page. A command of an older spelling, such as nylorun environments, nylorun key, or nylorun logs, exits 2 naming the new one.

start flags: --tenant <name>, --no-link, --no-studio, --allow-downgrade, --restate-ui, --studio-embed-origin, --studio-embed-origin-reset.

start passes NYLORUN_PUBLIC_URL from its shell to the Runtime container (default http://localhost:<port>): webhook URLs and the Runtime's sign-in metadata name it, so set it to a reverse proxy's URL when one is in front. start also passes the OTEL_* trace-export variables and NYLORUN_TRACE_CONTENT from its shell to the Runtime container. Unset, the Runtime exports no traces. See Traces. It also passes NYLORUN_TUNING, the Runtime's Host tuning, to the runtime, gateway, and harness containers. On a slow machine, give start itself longer waits with NYLORUN_CLI_TUNING; see The CLI's own waits.

Names

A command acts on one Tenant, chosen in this order:

  1. --tenant <name>
  2. NYLORUN_TENANT
  3. The project link
  4. For start in a project: the directory name
  5. Otherwise: default

Several Tenants run side by side. Each has its own containers, network, volumes, and ports. nylorun local ls lists them.

Ports and data

ListenerDefault
Runtime127.0.0.1:8787
Studio127.0.0.1:4161

Free ports are chosen when those are taken, and kept in the Tenant's .env. Restate's UI is published only with --restate-ui.

Containers: runtime, gateway, harness (all the Runtime image), studio, postgres 17, restate, s2-lite, rustfs, and sandboxes only after nylorun local sandbox enable.

State lives in ~/.nylorun/tenants/<name>/ (or NYLORUN_HOME): Tenant files, Docker compose, plugins, and keys/vault-kek. Session data lives in Docker volumes.

Keys

Every Tenant serves two APIs on its one Tenant URL, and each takes its own kind of key:

APIRoutesKeyClient
Runtime API/v1/* but /v1/tenant/*Application key@nylorun/agents
Management API/v1/tenant/*Management key@nylorun/admin

The other API answers 403 (key_role_mismatch). A management key never acts for a person. start gives a linked project both: the application key project and the management key project-management, in .nylorun/credentials.json.

npx nylorun tenant keys put backend            # an application key for an app server
npx nylorun tenant keys put ops --management   # a management key
npx nylorun tenant keys list

Each key prints once. Only this machine issues management keys. A management key can issue application keys (admin.keys.put(id)).

Upgrades

Each nylorun release pins its images. start refuses to run an older Runtime than the Tenant last ran. Pass --allow-downgrade only when both versions share a database schema.

Reset a Tenant

Two commands reset a Tenant, in different ways:

nylorun local resetnylorun tenant reset
Acts onThe local Tenant on this machine, through Docker.The Tenant, local or remote, through the Management API with a management key.
DeletesAll the Tenant's data: volumes, the Tenant directory, and the vault key. The next start creates it anew, with a new id, and relinks the project.The sessions (the default), the Agents with their secrets, disks, and sessions (--agents), or all the data (--all), after work in flight drains.
KeepsIts files and ports.The Tenant, its keys, and the project link.

Both ask first; pass --yes when not in a terminal. In Studio, the ⋯ menu of the Tenant page has Reset sessions…, Reset Agents…, and Reset everything…, which reset as nylorun tenant reset does, each after a confirm. nylorun local delete <name> --yes removes the Tenant entirely, vault key included.

Remote installations

apply, the tenant, agent-manifests, agents, sessions, and artifacts groups, status, and doctor sandbox act on a Tenant over its APIs, so they work on an installation on another machine too. Without --tenant, they act on the installation these variables name:

VariablesActs on
NYLORUN_RUNTIME_URL and NYLORUN_MANAGEMENT_KEYstatus, doctor sandbox, and tenant (the Management API)
NYLORUN_RUNTIME_URL and NYLORUN_SERVER_KEYapply, agent-manifests, agents, sessions, and artifacts (the Runtime API)
NYLORUN_RUNTIME_URL and NYLORUN_TOKENThe same, with your identity provider's token in place of the key
export NYLORUN_RUNTIME_URL=https://runtime.example.com
export NYLORUN_MANAGEMENT_KEY=...   # from your secret store
npx nylorun status
npx nylorun tenant keys put backend

NYLORUN_RUNTIME_URL alone names nothing. On a remote installation, tenant keys manages application keys only; management keys are issued on the Runtime's machine. The local commands always act on this machine.

Next step

On this page