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.
| Call | Does |
|---|---|
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 linearagents 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:
{
"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/delegateAt 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
type | Fields | Used by |
|---|---|---|
bearer | url, value, via?, identity?, toolPrefix? | MCP servers and HTTP tools at url: sends Authorization: Bearer <value>. |
headers | url, 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. |
workload | url, 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_secret | value, allowedHosts, inject? | A CLI in a pod sandbox. See Shell credentials. |
environment_variable | value | A 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 acredentialfails withhttp.credentialand 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:
status | A session would |
|---|---|
covered | Send credential: the Agent, the secret's name, and its via. |
missing | Call 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/acmeSee 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
});| Field | Meaning |
|---|---|
via | Send 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:
{
"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| Flag | Meaning |
|---|---|
--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. |
--sse | The server speaks sse. Default streamable-http. |
--tenant <name> | The local Tenant to ask. |
--json | Print 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"],
});type | Fields | The sandbox sees |
|---|---|---|
environment_secret | value, allowedHosts, inject? | $<name> set to nylorun_managed, never the value. |
environment_variable | value | $<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 field | Without inject | Example |
|---|---|---|
header | Authorization | PRIVATE-TOKEN |
format | Bearer {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.