NylorunDocsBeta
RunAgents

Secrets and credentials

Write the keys an Agent's MCP servers, HTTP tools, and shell use.

// The Agent's manifest declares the slot "linear":
// a bearer token for https://mcp.linear.app/mcp.
await client.agents.secrets.put("projects/acme", "linear", {
  value: process.env.LINEAR_TOKEN!,
});

await client.createSession({
  agent: "projects/acme",
  ownerUserId: authenticatedUser.id,
});

Secrets belong to an Agent. Your app server writes them on the Runtime API with an application key, and every session on the Agent uses them. Each Agent has its own; a key many Agents use is written into each. Model keys are separate: they stay in the Tenant; see Models.

PUT to an existing name replaces the secret; the next request uses the new value. Values are write-only: list, get, and delete return names, types, and bindings, never a value. An application key writes secrets in every Agent of the Tenant. Acting for a person with client.as(), writing one takes agents:write; a trusted issuer's token reaches only the Agents its identity file's agents grants.

CallDoes
client.agents.secrets.put(id, name, secret)Create or replace one: { value } for a slot, or a typed secret.
client.agents.secrets.list(id)Every secret's name, type, and binding.
client.agents.secrets.get(id, name)One secret's metadata.
client.agents.secrets.delete(id, name)Remove one.

In Studio, write them on the Agent page's Vault tab: it lists each slot the manifest declares, and Set value asks only for the value. From a terminal, nylorun agents secrets put <id> <name> reads a slot's value from standard input, never from the arguments:

printf %s "$LINEAR_TOKEN" | npx nylorun agents secrets put projects/acme linear

agents secrets list, get, and rm do the rest. Request and response shapes are on Write an Agent's secret.

Secret slots

An agent manifest declares its secrets in runtime.secrets: each name, its type, its binding, whether it is required, and a description, never a value. The harness section names the slot each MCP server or HTTP tool authenticates with in credential, and the slots a skill's scripts read in its secrets:

"harness": {
  "mcpServers": {
    "linear": { "name": "linear", "type": "streamable-http", "url": "https://mcp.linear.app/mcp", "credential": "linear" }
  }
},
"runtime": {
  "kind": "none",
  "secrets": {
    "linear": { "type": "bearer", "url": "https://mcp.linear.app/mcp", "required": true }
  }
}

Both are checked when the manifest is saved: a credential names a bearer or headers slot bound to the server's or tool's exact URL, and a skill's secrets name environment_secret or environment_variable slots, or the save is 422 manifest_inconsistent. A server that names no credential still matches a secret by its URL.

On an Agent whose manifest declares slots, a write sends the value: { value }, or { headers } for a headers slot. The slot's url comes from the manifest, so app code cannot change which server a key is for. A name the manifest does not declare is 409 secret_not_in_manifest, and so is a typed write whose url differs from the slot's.

Route a slot

A bearer or headers slot's write may also name via, where the credential's requests go (Host feature secret-routing). The manifest names the server's own URL, or a fixed name for an HTTP tool, and each installation routes it:

runtime.json
{
  "secrets": {
    "delegate": { "type": "bearer", "url": "https://tools.example.internal/delegate", "required": true }
  }
}
await client.agents.secrets.put("teams/web", "delegate", {
  value: token,
  via: "https://tools.prod.example.com/delegate",
});
printf %s "$TOKEN" | npx nylorun agents secrets put teams/web delegate --via https://tools.prod.example.com/delegate

At each request the secret's via wins, else the slot's via in the version the Agent runs, else none: the request goes to the slot's url. The slot's url still picks the credential. via takes the same URLs as Gateway credentials. An HTTP tool whose URL has {field} parameters can't be routed (http.credential). A Runtime without secret-routing refuses via on a value write (400). A secret's view shows the via in force, never its value.

To add a slot, save a manifest version that declares it. An Agent that tracks the manifest moves to it (see Versions); a version that adds a required slot waits for its value (waitingFor: "secrets", state input_required), so write the value then. While an Agent moves, a write is checked against the version it moves to. Secrets the version it runs does not declare stay, unused.

The Agent's view lists each slot in slots, with whether it is set. Studio's Vault tab marks the slots with no value. While a required slot of the version the Agent runs has none, the Agent's state is input_required, with the reason secret_unset (see State).

Typed secrets

An Agent whose manifest declares no secrets takes typed writes: the type, the binding, and the value together.

await client.agents.secrets.put("projects/beta", "linear", {
  type: "bearer",
  url: "https://mcp.linear.app/mcp",
  value: process.env.LINEAR_TOKEN!,
});

The CLI takes the same JSON from a file, or from standard input with -: nylorun agents secrets put <id> <name> <secret.json|->.

Secret types

typeFieldsUsed by
bearerurl, value, via?, identity?, toolPrefix?MCP servers and HTTP tools at url: sends Authorization: Bearer <value>.
headersurl, headers, via?, identity?, toolPrefix?MCP servers and HTTP tools at url: sends every header of the map, such as x-api-key, or two keys at once.
workloadurl, via, identity?, toolPrefix?MCP servers and HTTP tools at url, through the gateway at via: sends the Runtime's workload token. It holds no value. See The workload credential.
environment_secretvalue, allowedHosts, inject?A CLI in a pod sandbox. See Shell credentials.
environment_variablevalueA plain variable every command in the sandbox sees.

A slot declares the same fields without value or headers, and no slot is of type workload. For bearer, headers, and workload the name is a label of 1 to 64 letters, digits, ., _, and -. For environment_secret and environment_variable the name is the variable's name.

Header names may not be the MCP transport's own headers (Content-Type, Accept, Mcp-Session-Id, and the like), Idempotency-Key, or Nylorun-* (400). A credential header replaces a manifest header of the same name.

How a credential is chosen

A tool credential is bound to one URL: the URL the agent's manifest names for the MCP server or HTTP tool. A session uses the slot the server or HTTP tool names in credential, else the credential bound to its URL. An Agent holds at most one bearer or headers credential per URL; a second one is 409 credential_conflict at the write.

  • A match. It is sent. An HTTP tool gets one only when it sets credential.
  • No match. An MCP server is called without a credential; one that needs a key answers 401. An HTTP tool that names a credential fails with http.credential and is not sent.

A 401 from the server, or from the gateway named by via, reaches the model as credential_rejected and is not retried. So does a gateway's report that the server behind it answered 401, such as LiteLLM's auth_required for a token the provider revoked, even when the gateway itself answers 200; the server's discovery is then failed, so your product can ask the person to connect again. See MCP errors.

A key acts as whoever made it. Put a person's own token, such as a personal access token, in their own Agent with owner set to them (the owner guard), and a key that acts for your organization in the Agents your app gives everyone.

await client.agents.put("users/alice/tools", {
  manifest: "personal-tools", // kind "none", with a "linear" slot
  owner: "alice",
});
await client.agents.secrets.put("users/alice/tools", "linear", {
  value: process.env.ALICE_LINEAR_KEY!,
});

Coverage

Before opening sessions, check what an Agent's MCP servers and HTTP tools would get from its secrets, with the Admin SDK:

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

const admin = createAdmin();
const coverage = await admin.coverage({ agentId: "projects/acme" });

for (const entry of coverage.entries) {
  console.log(entry.status, entry.name, entry.message);
}

Each entry is one remote MCP server or HTTP tool credential the manifest version the Agent runs declares, its subagents' and a flow's stages included:

statusA session would
coveredSend credential: the Agent, the secret's name, and its via.
missingCall an MCP server without a credential, which only a public server accepts, or fail an HTTP tool with http.credential.

complete is true when every entry is covered. Nothing reads a secret or calls a server. In Studio, a session's Manifest tab shows this check for its Agent in the Deployed view. The CLI runs it with a management key:

npx nylorun tenant coverage --agent projects/acme

See Check an Agent's credentials.

Gateway credentials

Nylorun does not sign people in to MCP servers or refresh their tokens. For a server that takes only a person's OAuth sign-in, use an MCP gateway that holds each person's sign-in. Write one credential with the gateway's key, with via and an identity header:

await client.agents.secrets.put("users/u_7c41/web", "notion", {
  type: "bearer",
  url: "https://mcp.notion.com/mcp", // what the manifest names
  value: process.env.GATEWAY_KEY!, // the gateway's key
  via: "https://gateway.internal/mcp/notion", // where the requests go
  identity: { header: "X-User-Id" }, // the session owner
});
FieldMeaning
viaSend the requests to this URL instead of url. url still picks the credential, and tool names keep the manifest's server name. An https URL (http only to a loopback host) with no userinfo, query, or fragment.
identity{ header }: add the session's ownerUserId in this header, for a gateway that keeps each person's accounts. A session owned by installation sends none.

For a session owned by u_7c41, the gateway receives Authorization: Bearer <the gateway's key> and X-User-Id: u_7c41. The value comes from the session record; nothing the model or a manifest says changes it. Check that your gateway does not treat a missing identity header as an administrator or a default user. Every tool argument and result passes through the gateway.

Gateway tool prefix

Some gateways put a prefix before each tool name they list: LiteLLM's per-server endpoint lists GitHub's create_issue as github-create_issue, and no setting turns that off. Give the prefix in toolPrefix, with via:

await client.agents.secrets.put("users/u_7c41/web", "github", {
  type: "headers",
  url: "https://api.githubcopilot.com/mcp/", // what the manifest names
  via: "https://litellm.internal/mcp/github", // LiteLLM's endpoint for the server
  toolPrefix: "github-", // what LiteLLM puts before each tool name
  headers: { Authorization: `Bearer ${process.env.LITELLM_KEY!}` },
});

The Runtime takes the prefix off what the gateway lists, and calls each tool by the name the gateway listed. Tool names (github__create_issue), the manifest's tools settings, and tool policy rules then name the server's own tools, whether or not a gateway is in between. A listed tool that lacks the prefix keeps its name, and the server's mcp.discovered message names it.

A bearer or headers slot may name toolPrefix too, with or without its own via (Host feature secret-routing), so the manifest says how the gateway lists the tools and each installation routes them:

runtime.json
{
  "secrets": {
    "github": { "type": "headers", "url": "https://api.githubcopilot.com/mcp/", "toolPrefix": "github-", "required": true }
  }
}
await client.agents.secrets.put("teams/web", "github", {
  headers: { Authorization: `Bearer ${process.env.LITELLM_KEY!}` },
  via: "https://litellm.internal/mcp/github",
});

The prefix applies whenever the credential's requests go to a via. A write may also send toolPrefix when there is a via, the write's or the slot's; the slot's prefix wins, and a write that names another is accepted, with a warning in the Runtime's log. A fork keeps a secret's own toolPrefix and via, and a secret's view (list, get) shows the ones in force. A PUT to the same name replaces them with the rest of the credential.

The workload credential

A workload credential holds no value: the Runtime sends its own workload token, a short-lived token your platform rotates through a file, as Authorization: Bearer <token> to via, with the identity header when it sets one, and only when the operator allows via's origin. It fills no secret slot, so write it as a typed secret, bound to the URL the manifest names; a fork does not copy it. A 401 from the gateway is credential_rejected, with error.gateway naming its origin, so an expired or unrotated token shows.

await client.agents.secrets.put("users/u_7c41/web", "notion", {
  type: "workload",
  url: "https://mcp.notion.com/mcp",
  via: "https://connections.example.com/mcp/notion",
  identity: { header: "X-User-Id" },
});

The operator gives the Runtime the token and the origins it may go to; see The workload token. nylorun start does not pass the workload token's variables yet, so a local Tenant cannot use a workload credential.

Preview an MCP server

List a server's tools with an Agent's credential for its URL, before an agent names it. The preview connects, lists the tools within 15 seconds, and calls none.

npx nylorun tenant mcp inspect https://mcp.linear.app/mcp --server linear --agent projects/acme
FlagMeaning
--server <name>The server name the model's tool names are made with. Default: from the URL's host (linear for mcp.linear.app).
--agent <id>The Agent whose credential for the URL is sent. Without it, none is sent.
--sseThe server speaks sse. Default streamable-http.
--tenant <name>The local Tenant to ask.
--jsonPrint the answer as JSON.

admin.mcp.preview({ url, name?, type?, agentId? }) returns the same answer. Each tool comes with the name the model would call it in our harness, its hints, and the size of its input schema; renamed lists the tools whose model name is not <server>__<tool>. A preview sends the credential's headers and via, never an identity header.

A server that answers 401 returns authRequired instead of tools, with the server's sign-in metadata: it needs a key, or a gateway. A server that cannot be listed is 502 mcp_preview_failed, with details.failure the code a tool call would have had. See Preview an MCP server's tools.

Shell credentials

A skill that runs a CLI such as gh, aws, or curl in a pod sandbox authenticates with an environment_secret. The value never enters the sandbox. The secret's name is the variable's name, and the skill names the slots it reads in its secrets.

await client.agents.secrets.put("users/alice/web", "GH_TOKEN", {
  type: "environment_secret",
  value: process.env.ALICE_GITHUB_TOKEN!,
  allowedHosts: ["api.github.com", "github.com"],
});
typeFieldsThe sandbox sees
environment_secretvalue, allowedHosts, inject?$<name> set to nylorun_managed, never the value.
environment_variablevalue$<name> set to the value, such as a region. Every command in the sandbox can read it.

A name is a letter or _ followed by letters, digits, or _. PATH, HOME, the proxy and CA bundle variables, and NYLORUN_* are reserved.

When a command sends HTTPS to one of allowedHosts (exact host names, port 443, at most 32 by default, the Runtime limit secretHosts), the egress gateway sets a header on each request with the secret's value. inject names it, with both fields:

inject fieldWithout injectExample
headerAuthorizationPRIVATE-TOKEN
formatBearer {value}Basic {base64:x-access-token:{value}}

{value} appears once in format; {base64:…} encodes its part.

The value is read on every request, so a new value applies to the next one. A second environment_secret bound to a host another one has is 409 credential_conflict at the write. The host must also be in the manifest's network.allowedHosts. A CLI that pins certificates or ignores the standard CA bundle variables cannot use this path. Shell credentials reach pod sandboxes only: a virtual Agent gets the variables but no header. See Kubernetes.

Next step

On this page