Skip to navigation

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:

pip install "nemoguardrails[server]"
nemoguardrails hooks-server --config ./hooks-config

The command accepts the following options:

OptionDescription
--configThe configuration directory or file. Required, exactly once: one configuration is the whole policy, so the server refuses a second --config.
--hostThe interface to listen on. Default: 127.0.0.1.
--portThe port to listen on. Default: 8100.
--metrics-exporterExpose the admission-queue metrics on a scrape endpoint. Supported values: prometheus and none. Default: none. Refer to Metrics.
--metrics-hostThe interface for the scrape endpoint. Default: 127.0.0.1.
--metrics-portThe port for the scrape endpoint. Default: 9465.

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:

models: []
hooks_server:
allowed_tools:
- Bash
- Read
- Edit
allow_unlisted_tools: false
rails:
tool_call:
per_tool:
Bash:
- regex check tool call $argument=command
config:
regex_detection:
tool_call:
Bash:
patterns:
- '\brm\s+-rf\b'

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:

  1. The call’s shape. A tool_input that is not a JSON object is denied, with the reason tool call 'Bash' has arguments that aren't a JSON object.
  2. 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.
  3. 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:

SettingDefaultEffect
allowed_tools[]The tools a call may use. A name allows any arguments. A {name, arguments} entry allows only the listed argument names.
blocked_tools[]The tools a call may not use. A name blocks every call to the tool. A {name, arguments} entry blocks a call that passes any of the listed arguments.
allow_unlisted_toolstrueWhether a call to a tool that allowed_tools does not name is allowed. Set it whenever allowed_tools lists a tool: the server refuses to start an allowlist that leaves it unset.

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:

hooks_server:
allowed_tools:
- Bash
- Read
- Edit
- name: search
arguments: [query]
blocked_tools:
- WebFetch
- name: Bash
arguments: [run_in_background]
allow_unlisted_tools: false

The server applies the rules in the following order, and denies a call with the reason of the first rule it breaks:

OrderCall ConditionReason
1Names a tool that blocked_tools namestool call 'WebFetch' is a blocked tool
2Passes an argument that the tool’s blocked_tools entry liststool call 'Bash' passes argument 'run_in_background', which is blocked
3Names a tool that allowed_tools does not, while allow_unlisted_tools is falsetool call 'TodoWrite' is not an allowed tool
4Passes an argument that the tool’s allowed_tools entry does not listtool call 'search' passes 2 arguments its allowed_tools entry doesn't list

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:

hooks_server:
allowed_tools:
- name: Bash
arguments: [command, description, timeout]
blocked_tools:
- WebFetch
allow_unlisted_tools: true

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:

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, and Edit.
  • Codex reports shell commands as Bash and file edits as apply_patch, with the whole patch in the command argument.
  • 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:

nemoguardrails hooks-server --config examples/configs/agent_hooks/claude_code --port 8100
nemoguardrails hooks-server --config examples/configs/agent_hooks/codex --port 8101

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.

ExampleAllowsBlocks
claude_codeBash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearchDestructive Bash commands, and Read, Write, or Edit on secrets files such as .env
codexBash, apply_patch, update_planDestructive Bash commands, and patches that touch secrets files
nemo_relayAn application tool, search, with only a query argumentA search with an empty, missing, or non-string query

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:

  1. The configuration loads. The tool policy fails validation when a list names a tool twice, when allowed_tools allows a tool that blocked_tools blocks by name, when a {name, arguments} entry has an empty arguments list or names an argument twice, or when the hooks_server section or an entry has an unknown key:

    Invalid configuration: hooks_server: Value error, hooks_server.allowed_tools allows tool 'Bash', which hooks_server.blocked_tools blocks by name; remove it from one of the two lists.

    The configuration also fails to load when more than one of its files, or a configuration it imports, sets hooks_server:

    The hooks_server section is set in more than one file of this config, or of a config it imports; set it in one file only (found again in /path/to/hooks-config/policy.yml).
  2. The IORails engine can serve the configuration. The hooks server always runs on IORails, the engine that runs tool-call rails, and never falls back to LLMRails:

    The hooks server runs on IORails, which can't serve this config: IORails supports Colang 1.0 only; config uses Colang 2.x
  3. rails.tool_call.flows is empty. The server declares the called tool itself, so tool call validation always finds it and cannot deny a call:

    rails.tool_call.flows lists 'tool call validation', which can't deny a call on the hooks server: the server applies its tool policy and declares the called tool itself, so only per-tool rails check a call. Restrict tools with hooks_server.allowed_tools and hooks_server.allow_unlisted_tools: false, and remove the flow.
  4. Something can deny a call. The configuration needs a tool policy that can deny a call, or a per-tool rail:

    The hooks server needs a tool policy in the hooks_server section, or per-tool rails under rails.tool_call.per_tool; this config has neither, so every tool call would be allowed.

    A policy of names in allowed_tools alone denies nothing while allow_unlisted_tools is true, so it is refused too, with a message that says to set allow_unlisted_tools: false.

  5. The tool policy lets every per-tool rail run. Per-tool rails on a tool that blocked_tools blocks by name, or that allowed_tools does not list while allow_unlisted_tools is false, would never run:

    rails.tool_call.per_tool has rails for tool 'Bash', which hooks_server.allowed_tools doesn't list while hooks_server.allow_unlisted_tools is false, so they never run; add it to hooks_server.allowed_tools.
  6. A main model is one a rail uses. The hooks server never generates a response, so it refuses a main model 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 config has a `main` model, which the hooks server doesn't use: it checks tool calls and never generates a response, and no tool-call rail names `$model=main`. Remove the `main` model, or give the hooks server a config of its own.

    The hooks server ignores the tools a main model declares in parameters.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:

    The `main` model declares tools in parameters.tools, which the hooks server ignores, and the hooks_server section sets no tool policy that can deny a call, so every tool call would be allowed. List the tools in hooks_server.allowed_tools with allow_unlisted_tools: false, or remove parameters.tools.
  7. An allowlist sets allow_unlisted_tools. When allowed_tools lists a tool, allow_unlisted_tools must be set to false or true, because its default, true, would allow every tool the allowlist leaves out:

    hooks_server.allowed_tools lists tools while hooks_server.allow_unlisted_tools is unset, and its default, true, allows every tool allowed_tools doesn't list; set allow_unlisted_tools: false to allow only the listed tools, or true to allow the rest as well.
  8. The engine builds, and the metrics exporter starts, when you request one. For the exporter’s messages, refer to Prometheus and Grafana: Troubleshooting.

  9. The engine starts, and the server binds its port. An engine that fails to start ends the server with Application startup failed and 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 main model that a rail uses declares tools in parameters.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:

curl http://localhost:8100/v1/health

The server returns the following response:

{"status": "pass"}

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:

INFO:nemoguardrails.server.hooks.app:Hook check on /v1/hooks/claude-code: event=PreToolUse tool_name='Bash' tool_use_id='toolu_02' outcome=deny code=None rail='regex check tool 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:

nemoguardrails hooks-server --config ./hooks-config --metrics-exporter prometheus

Check the scrape endpoint with the following command:

curl -s http://127.0.0.1:9465/metrics | grep guardrails_

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:

pip install opentelemetry-distro opentelemetry-exporter-otlp
export OTEL_SERVICE_NAME=nemoguardrails-hooks-server
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
opentelemetry-instrument nemoguardrails hooks-server --config ./hooks-config

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.