nodrail

TypeScript SDK

Connect your agent’s tools to Nodrail Cloud for shared policies, approvals and decision history. A wrapped tool runs only after the client receives a fresh allow for the exact call. A denied request, a timeout or an invalid response blocks that invocation.

For local YAML policies, use the APF policy engine.

Developer preview: the API may still change before 1.0. Licensed under Apache-2.0. Report vulnerabilities privately, as described in SECURITY.md.

Quick start

You already have an agent with tools. Adding Nodrail is two lines of code and one environment variable; the tools, the agent and the framework stay as they are.

1. Get a credential

In Nodrail, open Agents → Connect an agent, choose TypeScript SDK, and copy the credential. It is shown once. Each agent gets its own, so a support bot and a coding bot can follow different rules.

2. Install and configure

npm install @nodrail/client

Keep the credential where your other API keys live: your .env file in development, and your host's secret settings in production (Vercel, Railway, AWS Secrets Manager, a Kubernetes secret, a CI secret).

NODRAIL_CREDENTIAL=ndr_...

3. Wrap the tools you already pass to your agent

Before:

const { text } = await generateText({ model, tools, prompt });

After:

import { guard } from "@nodrail/client";

const { text } = await generateText({ model, tools: guard(tools), prompt });

That's the whole integration. Full examples, each checked by the type checker on every change:

FrameworkExamplePass to guard
Vercel AI SDKvercel-ai-sdk.tsyour tools record
LangChain, LangGraphlangchain.tsyour tools array, or use the middleware
OpenAI Agents SDKopenai-agents.tsyour tools array
Your own loopplain-function.tsthe functions that do the work
Mastraa tool or record of tools
LlamaIndexa tool or array of tools
Anthropic SDK tool runneryour tools array
Claude Agent SDKthe tools from tool()
MCP SDKmcp-server.tsthe server, with guardMcpServer, see below
OpenAI SDK runToolsyour tools array

A framework's tools keep their exact type, so the result goes wherever the original went. A plain function now returns a promise, since it asks first. If guard doesn't recognise something it throws straight away, so a tool can never end up looking protected when it isn't.

What happens when the agent calls a tool

Before the tool's code runs, the client asks Nodrail whether this agent may make this call with these arguments. Your team's rules in Nodrail decide:

  • Allowed: the tool runs as before.
  • Denied: the tool doesn't run. The agent gets the reason as the tool's result, so it can tell the user or try something else.
  • Needs a person: someone gets the request in Nodrail and allows or denies it. The call waits up to 5 minutes for the answer, then counts as blocked and withdraws the request, so nobody approves a call that will not run.

Every decision is recorded. Rules change in Nodrail, without a deploy.

Try all three

Ask your agent to use a tool with no rule yet: the call waits, and the request appears in Nodrail under Approvals. Allow it there and the tool runs. Then, under Policies, add a rule that allows or denies that tool, and call it again.

In development and tests

Without a credential nothing throws: every guarded call is blocked and says the credential is missing. Set NODRAIL_WAIT_SECONDS=0 to block at once instead of waiting for a person. In unit tests of the tools themselves, test the unwrapped tools.

LangChain middleware

To cover every tool in a createAgent agent, including ones added while it runs:

import { nodrailMiddleware } from "@nodrail/client/langchain";

const agent = createAgent({ model, tools, middleware: [nodrailMiddleware()] });

Use this or guard. Using both still asks only once.

Rules that look inside a call

By default a tool is ruled by its name: tool send_email, operation call, resource type tool with the name as its id. A name that isn't already lowercase letters, digits, _ or - gets a short fingerprint (createIssue becomes createissue-1a2b3c4d), so prefer snake_case names, or describe the call yourself.

Rules see the tool's arguments under input, so a condition reads { field: input.amount, op: lte, value: 50 }. Arguments whose names look secret arrive as [redacted], and inputs over 16 KB arrive only as a fingerprint, so conditions can't see them.

To write rules about what a tool acts on, say so once:

guard(tools, {
  describe: {
    create_issue: (input) => ({
      tool: "github",
      operation: "issues.create",
      resource: { kind: "repository", id: (input as { repo: string }).repo },
    }),
  },
});

MCP servers

Guard the server before registering its tools. Every tool it registers from then on is checked under the name it registers with:

import { guardMcpServer } from "@nodrail/client";

const server = guardMcpServer(new McpServer({ name: "github", version: "1.0.0" }));

server.registerTool(
  "delete_repo",
  { inputSchema: { repo: z.string() } },
  async ({ repo }) => deleteRepo(repo),
);

The check goes inside each tool the server keeps, so it holds when the server calls the tool, and a later tool.update({ callback }) is checked too. Guarding a server that already has tools throws, rather than leaving them unchecked. A blocked call answers the MCP client with isError: true and the reason. Tested against the real @modelcontextprotocol/sdk client and server.

Options

OptionDefaultMeaning
waitMsNODRAIL_WAIT_SECONDS, or 5 minutesHow long a call waits for a person. 0 blocks at once and leaves the request open for a person to decide later.
onBlocked"return""throw", or a function, to change what a blocked tool does. Not used by the LangChain middleware, which always answers with an error message to the model.
describethe tool's nameWhat rules see for each tool. guard only.
namethe function's nameNeeded for a function with no name. guard only.
runNODRAIL_RUN, else no runThe run calls belong to when no inRun or step says otherwise. createNodrail() only.
envprocess.envWhere NODRAIL_* settings are read from. createNodrail() only.
fetchthe global fetchThe function requests to Nodrail use. createNodrail() only.
sleepa timerHow the client waits between checks for a person's answer, for tests. createNodrail() only.

waitMs and onBlocked also go to createNodrail(), which makes an instance with its own url, credential and adapterVersion. Each request to Nodrail times out after 10 seconds, and a call that waits for a person holds the agent until the answer or waitMs: keep that in mind in serverless functions with a short time limit.

Without a framework

import { createNodrail } from "@nodrail/client";

const nodrail = createNodrail();

// Runs only if allowed. Anything else throws NodrailBlockedError.
await nodrail.run(
  {
    tool: "github",
    operation: "issues.create",
    resource: { kind: "repository", id: "acme/support" },
  },
  () => createIssue(),
);

// Or ask, act on the answer yourself, and say how it went.
const decision = await nodrail.check({ tool: "github", operation: "issues.delete" });
if (decision.allowed) {
  await deleteIssue();
  await nodrail.report(decision, "success");
}

A plain string resource is resource type resource. With no resource, it is type tool with the id <tool>.<operation>, such as github.issues.delete. run() and check() send params exactly as you pass them, with no redaction: keep secrets out of them.

Runs and steps, for any framework

SDK walkthrough preview. The examples below require client 0.2.0 or later, which provides inRun and step.

Gates and budgets decide with what already happened in a piece of work: hold the pull request until QA passed after the last change, or limit how many tool calls one agent step makes. Tell Nodrail which run a call belongs to, and wrap each agent's work as a step:

const nodrail = createNodrail({ run: "ENG-42" }); // or NODRAIL_RUN

await nodrail.step("dev", () => devAgent.run(task));
const review = await nodrail.step("qa", () => qaAgent.run(task));
await nodrail.step("github", () => releaseAgent.run(task)); // a gate can hold its calls

Every guarded call made while a step runs belongs to it, through your agent framework's tool loop too, so tools need no change. Steps running side by side keep their own calls. nodrail.inRun(key, work) sets the run for one piece of work, for a server handling many.

A step's verdict comes from its result: a string ending with a nodrail-receipt block, or an object with verdict (and optional findings and usage: { tokens, usd }). Pass { receipt: (result) => … } as the third argument to read your own shape. A step that throws finishes with no verdict, and the error goes on. Recording a step never stops the work: if it can't be recorded, gates that need it stay closed.

step needs a run, and throws if there is none. Without a run, calls are decided as before, and any gate they match holds them.

Where the connection comes from

Nearest first: options you pass, then NODRAIL_URL and NODRAIL_CREDENTIAL, then the file credential in NODRAIL_HOME (by default ~/.nodrail). The URL defaults to https://app.nodrail.com. Only the credential is required. The address must use https; plain http is accepted only for this machine (localhost, 127.0.0.1, ::1), so the credential is never sent in the clear.

With no credential nothing throws at startup: each guarded call is blocked and says what is missing, and the next call looks again. So an application that loads its secrets after importing its tools is checked as soon as they are there.

When a call is blocked

The agent reads a sentence saying why, and NodrailBlockedError.code (or decision.code) says the same for your code:

CodeWhat it meansWhat to do
APPROVAL_PENDING, UNKNOWN_PERMISSION_BLOCKEDWaiting for a personAllow it in Nodrail under Approvals, then try again
DENIEDA rule or a person said noChange the rule, if it should be allowed
EXPIRED, INVALIDATEDThe request timed out, or something changedTry again for a new decision
NOT_CONFIGUREDNo credential foundSet NODRAIL_CREDENTIAL
UNAUTHENTICATEDThe credential was refusedCheck it, and that NODRAIL_URL points at your Nodrail
RATE_LIMITED, QUOTA_EXCEEDEDToo many calls, or the month's allowance is usedWait, or raise the plan
UNAVAILABLENodrail couldn't be reachedCheck the network; nothing ran
INSECURE_URLNODRAIL_URL is plain http to another machine, so the credential wasn't sentUse https. Plain http works only for localhost
INVALID_ACTIONThe call couldn't be described, for example a circular inputPass plain JSON arguments

What guard can't cover

  • Tools that run on a provider's servers, such as hosted web search, have no function here to check. guard leaves only these as they are: anything with code of its own (execute, handler, invoke, run, call, callback, func…) is wrapped, or refused with an error if its shape isn't recognised. A tool with two ways to run, such as both execute and run, is refused rather than half checked, and so is an MCP task tool.
  • MCP servers attached directly to an agent aren't wrapped. Use the tools from your MCP client, or the LangChain middleware.
  • Tools that never pass through guard, and code outside the agent.

Claude Code and Codex

Install the plugin instead: see Nodrail/agent-plugins. No code changes, and the checks cover the shell, file edits and MCP tools.

The one-file hook is also here, for setting up by hand: dist/nodrail-hook.mjs (also installed as the command nodrail-claude-hook), with the argument codex for Codex. @nodrail/client/setup exports the hook settings for both agents (claudeCodeHooks, codexHooks). The connect page in Nodrail shows them filled in.

The Claude Code hook sends each intent with its run and the subagent taking it, governs starting a subagent (Agent, or Task in older Claude Code), and records SubagentStart and SubagentStop as steps with the receipt block the subagent ended with (read from the last 16 KB of its message, up to 8 KB). The run is NODRAIL_RUN, else <repo>/<branch> where the session started, such as github.com/acme/app/fix-42, kept for the whole session so switching branch doesn't change it; on the default branch or outside git it is the session. The pin is kept in .git/nodrail/sessions. Gates and budgets in your rules use that history. Any other agent uses runs and steps in the SDK.

Upgrading: starting a subagent used to be ungoverned by the plugin. It is now tool claude-code, operation agent, with the subagent's type as a resource of type agent (vercel:deployment-expert becomes vercel-deployment-expert). Until a rule allows it, each start waits for a person. Rule files with a rule for the earlier resource, type tool with id Agent, no longer compile.

The Codex hook sends the run the same way. Codex doesn't say which subagent makes a call, so every call is the main agent's: gates on commands (such as git push) and budgets per run work, and a gate waiting for another agent's step holds until that step is recorded some other way, for example with nodrail.step() in a script.

To see all three outcomes, add these rules under Policies, then ask the agent to run the commands:

OutcomeRuleCommand
Allowed by a ruleAllow shell command.run, resource type command, starting with git statusgit status
Waits for a personNo rule needednpm publish --dry-run
DeniedDeny shell command.run, resource type command, exactly git pushgit push

Rule examples

examples/policies holds one rule file per pattern: read one resource, require review for writes, and deny a sensitive operation. Try them without an account using the policy engine's command line:

npx -p @nodrail/policy-engine nodrail-policy eval examples/policies \
  --tool github --operation issues.read --kind repository --resource acme/support

A simulation never approves anything or issues a permit.

Compatibility

ComponentSupportedChecked with
Claude Code2.1.295 or later, which adds onFailure2.1.322 on macOS, real CLI: a missing, timed-out or crashing hook blocks the tool
Codex0.155 or later0.155.1 on macOS, real CLI
LangChain1.x1.6 agent loop
Vercel AI SDK77.0 agent loop
OpenAI Agents SDK0.210.21 agent loop
MCP SDK1.x1.32 client and server
Mastra, LlamaIndex, Anthropic and OpenAI SDKs, Claude Agent SDKRecognised by shapeShape only
Node.js22 or later22 and 24
LinuxBlocking paths checked on Alpine, arm64Node 22 in Docker
WindowsSupportedNode 22 in CI; the agents' hooks not yet in the real CLIs
TypeScript consumersmoduleResolution: bundler or nodenextTypeScript 7
Protocolschema 1, canonicalizer 1

How a Claude Code call maps to a rule is part of the contract. A change to it uses new operation names or resource types, so an existing rule can never silently start matching something else; at worst it stops matching, and the call is blocked until the rule is updated.

Claude Code toolToolOperationResource
Bash, PowerShell (one simple command)shellcommand.runcommand
Bash, PowerShell (chains, redirects, substitution, or running another program)shellcommand.compoundcommand
Writefilesfile.writefile
Edit, MultiEditfilesfile.editfile
NotebookEditfilesnotebook.editfile
WebFetchwebfetchurl
WebSearchwebsearchquery
mcp__server__toolservertoolmcp_tool
Agent (starting a subagent)claude-codeagentagent, id the subagent's type
Codex apply_patch (one file)filesfile.write, file.edit or file.deletefile
Codex apply_patch (several files, or a rename)filesfile.patchfile, id patch:sha256:…
Any other toolclaude-codethe tool's name in lowercasetool

A command, URL or search that contains something that looks like a secret uses command.redacted, fetch.redacted or search.redacted instead, so a rule for the plain form can't cover it.

A name that is not already a lowercase key gets a short fingerprint, so GitHub and github can never share a rule.

What leaves your machine

  • File contents: never. Only a fingerprint and the path.
  • Commands, URLs, searches, MCP and tool inputs: sent so a person can review them, with anything that looks like a secret replaced by [redacted]. The filter is best effort, so keep secrets out of them. A fingerprint of the original binds an approval to the exact call.
  • Results: only whether the tool succeeded and how long it took.
  • Runs: the run key each call belongs to (NODRAIL_RUN, else the repository and branch, such as github.com/acme/app/fix-42, without any credentials in the remote's URL, else the session), the step's agent name, and the receipt a step ends with: in Claude Code, the nodrail-receipt block that ends a subagent's last message, not the rest of it; with nodrail.step(), the receipt read from the step's result.
  • run() and check(): params exactly as you pass them, with no redaction.

Limits

  • In Claude Code, reads (Read, Grep, Glob) aren't sent to Nodrail. The hook checks them on the machine and blocks any that reach a place credentials live, such as .env*, ~/.ssh or *.pem. The check covers only the tools matched in the hook settings: anyone who can edit those settings, or a process outside the agent, can go around it. This is not a sandbox.
  • File paths are resolved and URLs normalised before rules see them, in the machine's own form (C:\repo\ on Windows). Shell prefix rules are a convenience, not a sandbox: prefer exact rules for commands.
  • A person's approval covers one call. Retrying after the wait creates a new request.
  • Each installation can make 600 calls a minute.
  • A workspace has a monthly allowance of agent actions. Past it, new actions are blocked. Checks never stop running and nothing becomes allowed.