Run the Hooks Server
The Guardrails hooks server (nemoguardrails hooks-server) loads one guardrails configuration at startup.
It checks each tool call against that configuration’s tool policy and per-tool rails.
Use this guide to configure, start, and monitor the server.
To connect an agent, refer to the Claude Code, Codex, or NeMo Relay page.
Start the Server
Install the NVIDIA NeMo Guardrails library with the server extra, then start the hooks server with one configuration:
The command accepts the following options:
The hooks server has no options for a chat UI, a path prefix, auto-reload, or a default configuration ID, which belong to the Guardrails API server. For the full option reference, refer to CLI: hooks-server.
Write a Hooks Configuration
A hooks configuration is a config.yml with two parts: the tool policy in the top-level hooks_server section, and per-tool rails under rails.tool_call.per_tool.
It needs no model:
With this configuration, the hooks server denies a call to any tool other than Bash, Read, and Edit, and denies a Bash command that matches the pattern.
For each call, the hooks server applies three checks in order, and the first to deny the call decides:
- The call’s shape. A
tool_inputthat is not a JSON object is denied, with the reasontool call 'Bash' has arguments that aren't a JSON object. - The tool policy decides which tools a call may use and which arguments it may pass. The server applies it itself, and answers a call it denies without running any rail.
- Per-tool rails check the calls the policy allows, for the tools they are listed under.
The configuration needs a tool policy that can deny a call, per-tool rails, or both, as described in Startup Checks.
The Tool Policy
Three settings in the hooks_server section make up the tool policy:
Set allow_unlisted_tools: false to deny every tool you have not listed, including tools that a later agent release adds.
With allow_unlisted_tools: true, unlisted tools are allowed too, so a name in allowed_tools has no effect, and an entry only limits its tool’s arguments.
The default, true, suits a policy of blocked_tools or per-tool rails alone.
When allowed_tools lists a tool, set allow_unlisted_tools to false or true yourself: the server refuses to start an allowlist that leaves it unset, so that the default cannot quietly allow the tools the allowlist leaves out.
A tool with only an argument entry in blocked_tools is still unlisted, so allow_unlisted_tools: false denies it unless allowed_tools names it too.
The following policy allows four tools, allows search only with a query argument, and denies Bash calls that pass run_in_background:
The server applies the rules in the following order, and denies a call with the reason of the first rule it breaks:
A reason quotes only names from your configuration and the called tool’s name. For arguments the agent chose, it gives a count rather than their names.
To allow every tool but limit the arguments of a few, set allow_unlisted_tools: true and give those tools {name, arguments} entries in allowed_tools.
Use this when you cannot list every tool that the agent uses, such as an agent with many Model Context Protocol (MCP) tools, but want a sensitive tool to accept only the arguments you know:
With this policy, every tool except WebFetch runs, and a Bash call that passes any other argument is denied, including an argument that a later agent release adds.
A {name, arguments} entry in blocked_tools denies only the arguments it names, so it cannot catch an argument that you do not know about yet.
A name without arguments in allowed_tools has no effect while allow_unlisted_tools is true, so list only {name, arguments} entries.
A per-tool rail on a tool with an entry must name one of the entry’s arguments in $argument=, as described in Per-Tool Rails.
Set hooks_server in one file of the configuration.
A configuration where more than one file, or a configuration it imports, sets hooks_server fails to load, so that no file can widen another file’s policy.
The Guardrails API server and the Python API ignore the hooks_server section.
For the field reference, refer to Configuration Reference: Hooks Server Tool Policy.
Per-Tool Rails
List the rails for each tool under rails.tool_call.per_tool, keyed by the tool’s name.
The following rails check a tool call:
regex check tool callmatches regular expressions against the call’s arguments, with no model.cel check tool callevaluates Common Expression Language (CEL) expressions over the call’s arguments, with no model.tool safety check tool callasks a judge model whether the call is safe, so the configuration needs that model.
Add $argument=<name> to a regular-expression rail or a tool safety check to scope it to one argument, such as $argument=command for a shell command or $argument=file_path for a file path.
When a call does not pass the argument, a regular-expression rail checks all the call’s arguments.
A CEL rail takes no $argument=, and the server refuses to start with one; a CEL expression names the arguments it reads.
The rails for a tool run in the order listed, and the first rail to block the call or to fail decides.
List a rail that can fail, such as a tool safety check whose judge model can be unreachable, after the rails that cannot, such as regular expressions.
With the judge listed first, a call that a regular expression would deny gets an error instead whenever the judge’s model call fails.
With rails.tool_call.parallel: true, a tool’s rails run at once, and the first to block or fail decides.
A hook carries the agent’s call but no tool definitions, and per-tool rails check a call against the tool’s definition before they run.
So the hooks server declares the called tool to the rails itself, from the tool’s allowed_tools entry:
- A name, or no entry, declares a tool that takes any arguments.
- A
{name, arguments}entry declares a tool that takes only the listed arguments.
The declaration exists only so that the rails can run, and is not the tool’s real schema.
It has one consequence: when a tool has a {name, arguments} entry, a rail’s $argument= must name one of the entry’s arguments.
Otherwise the rail fails on every call to the tool, the server logs argument 'limit' is not declared in tool 'search' schema, and every call gets an error.
Tools that a model declares in its parameters.tools play no part in a check, as described in Startup Checks.
rails.tool_call.flows, such as tool call validation, cannot deny a call on the hooks server, so the server refuses it.
The server runs only tool-call rails, and ignores the input, output, and tool-result rails of the configuration without a warning, so leave them out of a hooks configuration.
Tool Names
The hooks server matches tool names exactly as the agent sends them, in allowed_tools, blocked_tools, and per_tool alike.
Names are never patterns.
- Claude Code sends its own tool names, such as
Bash,Read,Write, andEdit. - Codex reports shell commands as
Bashand file edits asapply_patch, with the whole patch in thecommandargument. - Both agents send MCP tools as
mcp__<server>__<tool>. - NeMo Relay forwards the names of whatever tools it wraps.
The hooks server checks tool_input as the agent sends it, and does not convert between agents’ tool formats.
A rail for file edits therefore needs Write and Edit in Claude Code’s configuration, and apply_patch in Codex’s.
For each agent’s tool names and arguments, refer to its page.
One Server for Each Agent
The hooks server applies its one configuration on every path it serves, and both Claude Code and Codex report shell commands as Bash, so a Bash entry in one configuration would apply to both agents’ calls.
To check tool calls from more than one agent, run a hooks server for each agent, with that agent’s configuration and on its own port:
Point each agent’s hook at its own server, replacing port 8100 in the hook settings on the agent’s page with that server’s port.
When you run the metrics exporter, give each server its own --metrics-port too.
Example Configurations
The repository includes one example configuration for each agent in examples/configs/agent_hooks.
Each one allows a starting set of tools, denies every other tool, and blocks a few risky calls with regular expressions, so none needs a model or an API key.
The patterns illustrate a policy structure and do not provide complete protection. Regular expressions can be bypassed, so combine them with the agent’s permission settings and sandboxing.
Startup Checks
The hooks server checks its configuration before it accepts any request.
If a check fails, the server exits without serving, so a misconfiguration never surfaces as failed tool calls.
For every check but the last, it prints a one-line reason and exits with status 1.
The server checks the following, in order:
-
The configuration loads. The tool policy fails validation when a list names a tool twice, when
allowed_toolsallows a tool thatblocked_toolsblocks by name, when a{name, arguments}entry has an emptyargumentslist or names an argument twice, or when thehooks_serversection or an entry has an unknown key:The configuration also fails to load when more than one of its files, or a configuration it imports, sets
hooks_server: -
The
IORailsengine can serve the configuration. The hooks server always runs onIORails, the engine that runs tool-call rails, and never falls back toLLMRails: -
rails.tool_call.flowsis empty. The server declares the called tool itself, sotool call validationalways finds it and cannot deny a call: -
Something can deny a call. The configuration needs a tool policy that can deny a call, or a per-tool rail:
A policy of names in
allowed_toolsalone denies nothing whileallow_unlisted_toolsistrue, so it is refused too, with a message that says to setallow_unlisted_tools: false. -
The tool policy lets every per-tool rail run. Per-tool rails on a tool that
blocked_toolsblocks by name, or thatallowed_toolsdoes not list whileallow_unlisted_toolsisfalse, would never run: -
A
mainmodel is one a rail uses. The hooks server never generates a response, so it refuses amainmodel unless a tool-call rail names it with$model=main, as a tool safety check judge can. A configuration written for the Guardrails API server therefore needs a hooks configuration of its own:The hooks server ignores the tools a
mainmodel declares inparameters.tools. So that a configuration that relied on them as an allowlist does not allow every tool, the server refuses them unless the tool policy can deny a call: -
An allowlist sets
allow_unlisted_tools. Whenallowed_toolslists a tool,allow_unlisted_toolsmust be set tofalseortrue, because its default,true, would allow every tool the allowlist leaves out: -
The engine builds, and the metrics exporter starts, when you request one. For the exporter’s messages, refer to Prometheus and Grafana: Troubleshooting.
-
The engine starts, and the server binds its port. An engine that fails to start ends the server with
Application startup failedand a traceback.
A server that answers its health check has passed every startup check.
The server also logs a warning in the following cases, and starts anyway:
- The
mainmodel that a rail uses declares tools inparameters.tools, which the hooks server ignores. - The metrics exporter is running, but the configuration does not set
metrics.enabled: true.
Health Check
The hooks server answers the same liveness checks as the Guardrails API server, GET /v1/health and GET /healthz:
The server returns the following response:
The response means the process is up and has passed its startup checks.
The server answers every other path with HTTP 404, and a hook path called with another method than POST with HTTP 405.
It has no OpenAPI or docs pages.
Logs
The hooks server logs one line for each tool call it checks, with the agent’s path, the tool name, the agent’s call ID, the outcome, the error code, and what decided the call:
rail names the per-tool rail that blocked or failed, tool policy for a call the tool policy denied, or None when no rail decided, such as for an allow.
A check that ends in an error is logged at the WARNING level.
The line never includes the tool’s input, which can carry file contents or credentials.
The nemoguardrails hooks-server command logs at the INFO level only from the hooks server, from Uvicorn, the web server, for startup and requests, and from the IORails engine.
The engine’s lines carry timings, outcomes, and each model request’s URL and model name, but no message content.
The library’s other loggers stay at WARNING.
A tool safety check sends the call’s arguments to its judge model, but the server logs neither the arguments nor the judge’s prompt.
A request the server answers before checking a call gets no such line: a 422 for a malformed request, a 503 when the admission queue is full, or a 500 for an unexpected error.
The server’s error handlers log those in their own format.
Metrics
The hooks server can expose the IORails admission-queue metrics on a Prometheus scrape endpoint, as the Guardrails API server does.
Set metrics.enabled: true in the configuration, then start the server with the exporter:
Check the scrape endpoint with the following command:
The hooks server has its own defaults, so it can export beside the Guardrails API server on one host: the scrape endpoint listens on 127.0.0.1:9465, and the service.name resource attribute is nemoguardrails-hooks-server.
The queue gauges appear as soon as the server starts.
Only calls that run per-tool rails pass through the admission queue, so a call that the tool policy decides, or a call to a tool with no per-tool rails, does not change the metrics.
The exporter reads the same NEMO_GUARDRAILS_SERVER_METRICS_* environment variables as the Guardrails API server, and a variable overrides the hooks server’s default.
A variable exported for the Guardrails API server in the same shell therefore also applies to the hooks server, and can turn on its export, move its endpoint off 127.0.0.1, or make it collide with the other server’s port.
Set the hooks server’s exporter with its own flags.
For the variables and the Prometheus and Grafana setup, refer to Prometheus and Grafana: The Hooks Server.
Tracing
To trace the checks, set tracing.enabled: true in the configuration and run the server under the OpenTelemetry opentelemetry-instrument launcher, which installs the OpenTelemetry SDK:
Point the exporter at your collector with the standard OpenTelemetry variables, such as OTEL_EXPORTER_OTLP_ENDPOINT, or set OTEL_TRACES_EXPORTER=console to print spans for a first check.
A call that runs per-tool rails produces one guardrails.request span, with a guardrails.rail span for each rail that runs and a guardrails.action span for each action.
A call that the tool policy decides, or a call to a tool with no per-tool rails, runs no rail and produces no span; the log line records it.
For the span attributes, refer to Span Reference.
Use either opentelemetry-instrument or --metrics-exporter, not both.
The launcher installs a global OpenTelemetry meter provider even with OTEL_METRICS_EXPORTER=none, so the built-in exporter then refuses to start.
With content capture on, the spans record each checked call’s arguments, which are the agent’s tool_input.
A tool input can carry the content of a file the agent writes, or a credential in a shell command.
Content capture is off by default; leave it off unless your trace backend may store that data.
For details, refer to Capturing Prompt and Response Content.
Expose the Server
The hooks server has no authentication, like every Guardrails server.
It listens on 127.0.0.1 by default, so only processes on the same machine can reach it.
To serve agents on other machines, set --host to an interface on a private network, and restrict who can reach the port with a firewall or network policy.
Do not expose the hooks server to the public internet: anyone who can reach it can send it tool calls and learn what the policy allows.
Apply Configuration Changes
The hooks server loads its configuration when it starts, and has no auto-reload. Restart the server to apply a change. While it restarts, agents get connection errors, which their hook configuration answers by blocking the call or by running it. For how to make each agent block, refer to Results and Errors: Block a Call When a Check Fails.