Admin SDK
The TypeScript client operators' tools use to call the Management API.
npm install @nylorun/adminimport { 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
| Group | Endpoints |
|---|---|
admin.tenant | Tenant |
admin.keys | Application keys |
admin.models | Models |
admin.toolPolicy | Tool policy |
admin.coverage() | Credential coverage |
admin.mcp | MCP servers |
admin.signingKeys | Signing keys |
admin.settings.sandbox, admin.settings.artifacts | Settings |
admin.settings.limits | Runtime limits |
admin.settings.skills | Skill 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:
- Explicit
{ url, key }, both or neither NYLORUN_RUNTIME_URLandNYLORUN_MANAGEMENT_KEY- The local Tenant: the project link and the
project-managementkey thatnylorun startwrote
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
| Option | Type | Purpose |
|---|---|---|
url | string | The Tenant's URL |
key | string | A management key |
tenant | string | The local Tenant to read, instead of the project link's |
cwd | string | Where 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 runs | Command |
|---|---|
| Local Tenant | npx nylorun tenant keys put <id> --management |
| Self-hosted Runtime container | nylorun-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.
| Field | Type | Purpose |
|---|---|---|
code | ErrorCode | The cause: the Runtime's code, else derived from the status |
status | number | undefined | The HTTP status, when the Runtime answered |
details | unknown | Extra data from the Runtime |
Codes
| Code | Cause |
|---|---|
connection_missing | No URL and management key resolved, or a project link or credentials.json does not validate |
incompatible_host | The Runtime does not serve protocol 18 with the Management API |
credential_required | No management key was sent (401) |
credential_invalid | The Tenant does not know the key: rotated, deleted, or another Tenant's (401) |
key_role_mismatch | An application key was sent to the Management API (403) |
subject_invalid | A management key was sent with Nylorun-Subject or Nylorun-Scopes (403) |
origin_rejected | A 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:
| Status | code |
|---|---|
400 | invalid_request |
401 | credential_invalid |
404 | not_found |
415 | unsupported_media_type |
5xx | internal_error |
| Any other | request_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
| Function | Returns |
|---|---|
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.
Open a capability link GET
Downloads the version the link names, with Range, until it expires (`401 token_expired`): a file, a folder's file, or a folder's zip. Needs no credential and no `Nylorun-Protocol`.
Get who the caller is GET
The subject, scopes and Agent grants of the credential that sends it: an application key (alone or acting for a subject), a management key (`via: management:<principalId>`, no scopes, no agents), or a trusted issuer's token (`via: issuer:<name>`).