Local Tenants
Start, stop, and inspect one Nylorun installation per project.
npx nylorun startIn 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.
| Command | What 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> --yes | Remove containers, volumes, files, and the vault key. |
local telemetry status|enable|disable | Studio 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:
--tenant <name>NYLORUN_TENANT- The project link
- For
startin a project: the directory name - 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
| Listener | Default |
|---|---|
| Runtime | 127.0.0.1:8787 |
| Studio | 127.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:
| API | Routes | Key | Client |
|---|---|---|---|
| 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 listEach 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 reset | nylorun tenant reset | |
|---|---|---|
| Acts on | The local Tenant on this machine, through Docker. | The Tenant, local or remote, through the Management API with a management key. |
| Deletes | All 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. |
| Keeps | Its 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:
| Variables | Acts on |
|---|---|
NYLORUN_RUNTIME_URL and NYLORUN_MANAGEMENT_KEY | status, doctor sandbox, and tenant (the Management API) |
NYLORUN_RUNTIME_URL and NYLORUN_SERVER_KEY | apply, agent-manifests, agents, sessions, and artifacts (the Runtime API) |
NYLORUN_RUNTIME_URL and NYLORUN_TOKEN | The 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 backendNYLORUN_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.