NylorunDocsBeta
Management API

Admin SDK

The TypeScript client operators' tools use to call the Management API.

npm install @nylorun/admin
import { createAdmin } from "@nylorun/admin";

const admin = createAdmin();

const status = await admin.tenant.status();
const { key } = await admin.keys.put("backend"); // an application key, shown once

@nylorun/admin calls the Management API with a management key. Operators' tools use it: CI jobs, scripts, and internal consoles. Your app server does not; it calls the Runtime API through @nylorun/agents. It requires Node 24 or later.

Each endpoint page in this section shows the SDK call first, then cURL. A request body's requestId is optional; the client generates one.

The client

GroupEndpoints
admin.tenantTenant
admin.keysApplication keys
admin.modelsModels
admin.toolPolicyTool policy
admin.coverage()Credential coverage
admin.mcpMCP servers
admin.signingKeysSigning keys
admin.settings.sandbox, admin.settings.artifactsSettings
admin.settings.limitsRuntime limits
admin.settings.skillsSkill limit

admin.models.setInputs({ provider, model, inputs }) adds inputs to a catalog model: only those in its addableInputs, and an empty list removes the additions. A custom endpoint sets settings.inputs with admin.models.put() instead. See Models.

await admin.models.setInputs({
  provider: "openai",
  model: "gpt-4.1",
  inputs: ["pdf"], // added to what its catalog reads
});

A custom endpoint behind a model gateway takes headers that are not credentials: settings.headers go on every call, and settings.callHeaders take their value per call from the calling Agent ({ from: "agent.label", key }, { from: "agent.id" }, or { from: "session.owner" }). Neither may set authorization, a hop-by-hop header, or Nylorun-*. auth: { type: "workload" } sends the Runtime's workload token as the endpoint's bearer instead of a stored key:

await admin.models.put({
  idempotencyKey: "model-gateway",
  provider: "custom",
  model: "claude",
  baseUrl: "https://litellm.internal/v1",
  auth: { type: "workload" }, // or { type: "api_key", key }
  settings: {
    callHeaders: { "x-nylorun-org": { from: "agent.label", key: "org" } },
  },
});

An Agent's secrets are written on the Runtime API with an application key, through client.agents.secrets in @nylorun/agents. A management key checks them against the manifest version the Agent runs, and previews a server with them:

await admin.toolPolicy.put({
  rules: [
    { effect: "ask", agent: "support", tool: "refund_order" },
    { effect: "ask", server: "linear", tool: "create_issue" }, // an MCP tool
  ],
});

const coverage = await admin.coverage({ agentId: "teams/support" });

const preview = await admin.mcp.preview({
  url: "https://mcp.linear.app/mcp",
  agentId: "teams/support", // sends that Agent's credential for the URL
});

A rule names an MCP tool by server and its own tool name, also through a gateway whose credential has a toolPrefix; a tool that holds __ is refused with 400. See Tool policy.

The Tenant's Runtime limits are one document:

const { limits } = await admin.settings.limits.get(); // every limit in force

await admin.settings.limits.put({
  limits: { sessionQueuedMessages: 20, httpToolTimeoutMs: 600_000 },
});

A put replaces every limit: one left out takes its default, so send the limits you set before with the new one. get() answers every limit in force, defaults included; putting it back whole pins today's defaults.

What an agent manifest may hold is three of these limits: folderFiles (2,000), folderBytes (50 MiB), and folderTextFileBytes (1 MiB). nylorun and packFolder() hold a folder to those defaults whatever the Tenant sets. See Runtime limits.

admin.tenant.reset({ scope: "agents", activeWork: "cancel" }) deletes the Tenant's Agents ("sessions" and "all" are the other scopes), and admin.models.usage({ scope: "manifest", id, period }) reads model usage for every Agent made from one agent manifest.

Connect

import { createAdmin } from "@nylorun/admin";

const admin = createAdmin(); // options, environment, then the local Tenant

const deployed = createAdmin({
  url: process.env.NYLORUN_RUNTIME_URL!,
  key: process.env.NYLORUN_MANAGEMENT_KEY!,
});

createAdmin() resolves the URL and the management key once, in this order:

  1. Explicit { url, key }, both or neither
  2. NYLORUN_RUNTIME_URL and NYLORUN_MANAGEMENT_KEY
  3. The local Tenant: the project link and the project-management key that nylorun start wrote

NYLORUN_RUNTIME_URL without NYLORUN_MANAGEMENT_KEY is an app's connection, so it does not select step 2. admin.source says which step was used (options, environment, or local-host).

When none resolves, createAdmin() throws connection_missing and lists what it tried. A project link or credentials.json that does not validate is also connection_missing, naming the file. The first request checks the Runtime's /health and throws incompatible_host unless it serves protocol 18 (Runtime 0.29 or later).

Options

OptionTypePurpose
urlstringThe Tenant's URL
keystringA management key
tenantstringThe local Tenant to read, instead of the project link's
cwdstringWhere to look for the project link: the nearest .nylorun/ from here upward, never at or above the home directory. Default: the working directory

Management keys

Only the Tenant's machine issues management keys. No API call creates one.

Where the Tenant runsCommand
Local Tenantnpx nylorun tenant keys put <id> --management
Self-hosted Runtime containernylorun-operate keys put <id> --role management

A management key acts as itself, never for a person. It can issue application keys, but never another management key.

Errors

import { AdminError } from "@nylorun/admin";

try {
  await admin.keys.put("backend");
} catch (error) {
  if (error instanceof AdminError && error.code === "key_role_mismatch") {
    // an application key was sent to the Management API
  }
  throw error;
}

Every failure is an AdminError.

FieldTypePurpose
codeErrorCodeThe cause: the Runtime's code, else derived from the status
statusnumber | undefinedThe HTTP status, when the Runtime answered
detailsunknownExtra data from the Runtime

Codes

CodeCause
connection_missingNo URL and management key resolved, or a project link or credentials.json does not validate
incompatible_hostThe Runtime does not serve protocol 18 with the Management API
credential_requiredNo management key was sent (401)
credential_invalidThe Tenant does not know the key: rotated, deleted, or another Tenant's (401)
key_role_mismatchAn application key was sent to the Management API (403)
subject_invalidA management key was sent with Nylorun-Subject or Nylorun-Scopes (403)
origin_rejectedA key was sent from a browser (403)

Other codes come from the Runtime and are listed on each endpoint page.

When an answer has no Runtime error body, such as one from a proxy, code follows the HTTP status:

Statuscode
400invalid_request
401credential_invalid
404not_found
415unsupported_media_type
5xxinternal_error
Any otherrequest_rejected

In a browser

A management key never leaves your server: the Runtime refuses any key sent with an Origin header. A browser UI calls your own server, which adds the key. createManagementClient() from @nylorun/admin/client is the same client without Node modules, for that browser side:

import { createManagementClient } from "@nylorun/admin/client";

const admin = createManagementClient({ url: "/api/nylorun-admin" });

Studio helpers

FunctionReturns
mintStudioLoginToken({ studioUrl, adminKey, subject? })A single-use Studio login token, for an app that embeds Studio
deriveStudioToken(adminKey)Studio's key, derived from the admin key

Both take the admin key, which only the Tenant's machine holds. See Studio in Guides.

On this page