Overview of the Guardrails Hooks Server
The Guardrails hooks server (nemoguardrails hooks-server) checks each tool call a coding agent is about to run, and answers before the agent runs it.
It provides the following capabilities:
- Receives each tool call from the agent’s own pre-tool hook: an HTTP hook in Claude Code, a command hook in Codex, or a tool conditional-execution guardrail in a NeMo Relay plugin.
- Applies a tool policy that allows or blocks tools, and their arguments, by name.
- Runs per-tool rails on calls the policy allows. Options include regular expressions, Common Expression Language (CEL) expressions, and a tool safety check judged by a large language model (LLM).
- Answers in each agent’s own hook output format, so the agent cancels a denied call and tells its model why.
- Needs no model, unless a rail you configure calls one.
How a Check Works
The agent sends each tool call to the hooks server before it runs the tool. The hooks server checks the call in three steps, and the first step that denies the call decides:
- The call’s shape. Arguments that are not a JSON object are denied.
- The tool policy. The
hooks_serversection of the configuration names the tools a call may use and the arguments it may pass. - Per-tool rails. The rails listed for the called tool under
rails.tool_call.per_toolcheck the call’s arguments. A tool with no per-tool rails is checked by the tool policy alone.
The hooks server then returns one of three outcomes:
- Allow: the call passed every step. The hooks server returns no decision, so the agent’s own permission rules still apply, including any prompt to the user.
- Deny: the tool policy or a rail blocked the call. The agent cancels the call and shows the reason, prefixed with
NeMo Guardrails:, to its model. - Error: the check could not finish, for example because a rail’s model call failed. The hooks server returns a non-
2xxstatus, and the agent’s hook configuration decides whether the call is blocked or runs.
The hooks server applies its one configuration on every path it serves. The path selects only the agent’s request and response format, never the policy. The policy and the rails are chosen by the tool name in each call, spelled exactly as the agent sends it, so run one hooks server for each agent.
The Hooks Server and the Guardrails API Server
The Guardrails hooks server and the Guardrails API server run as separate processes. The following table compares their commands, endpoints, and configuration requirements:
Metrics export is disabled by default on both servers.
Enable it with --metrics-exporter prometheus or NEMO_GUARDRAILS_SERVER_METRICS_EXPORTER=prometheus.
Both servers answer the same health checks, GET /v1/health and GET /healthz, and return errors in the same envelope.
A configuration written for one server does not serve the other: the hooks server refuses a main model that no rail uses, and the Guardrails API server ignores the hooks_server section.
To guard an application’s chat traffic and its agent’s tool calls, run both servers, each with its own configuration.
The Guardrails API server’s /v1/checks endpoint can also check tool calls, for an application that calls its own model and passes the tools it offered.
The hooks server is for agents whose code you do not control, and that can only call out from a hook.
For /v1/checks, refer to Checking Messages Against Rails.
Supported Agents
The hooks server supports the following agent integrations:
The hooks server handles only the PreToolUse event, and the NeMo Relay guardrail that stands in for it.
Any other hook event returns HTTP 422, so register the hooks server on PreToolUse only.
Quick Start
The following steps start the hooks server with the Claude Code example configuration and send it tool calls, the way Claude Code’s hook would.
Prerequisites
Install the NVIDIA NeMo Guardrails library with the server extra.
For instructions, refer to Extra Dependencies.
The example configuration uses only regular-expression rails, so it needs no model and no API key.
Start the Server
From a clone of the repository, start the hooks server with the Claude Code example configuration:
The server listens on http://127.0.0.1:8100.
Send Tool Calls
-
Send a
Bashcall that the configuration allows:The call is allowed, so the response carries no decision:
-
Send a force push, which a per-tool rail in the configuration blocks:
The call is denied, with the name of the rail that blocked it:
-
Send a call to
TodoWrite, a tool that the configuration’s tool policy does not list:The tool policy denies the call before any rail runs:
-
To check your agent’s calls for real, connect it to the hooks server: Claude Code, Codex, or NeMo Relay.
Known Limits
The hooks server checks the calls that reach it. Plan your deployment around what it cannot enforce:
- Hook settings can be edited. Anyone who can edit the agent’s hook settings can remove the hook, point it elsewhere, or make it let calls run when a check fails. To prevent that, deploy the hook through the agent’s managed settings, as described on the Claude Code and Codex pages.
- Some tool uses never reach the hook.
In Claude Code, files referenced with
@in a prompt are read without a tool call. In Codex, hosted tools such as web search run on the model provider’s side. The hooks server never sees those calls. - The server has no authentication.
Anyone who can reach it can send it calls, and so learn what the policy allows.
It listens on
127.0.0.1by default, so only the same machine can reach it. That includes the agent itself, which can call the endpoint from its own shell tool. Expose it on another interface only on a private network. - A policy without an allowlist allows every other tool.
With only
blocked_toolsor per-tool rails, the server allows a call to any tool they do not deny, including tools that a later agent release adds. To deny the tools you have not listed, list the allowed ones inallowed_toolswithallow_unlisted_tools: false, as the example configurations do. Refer to Run the Hooks Server: The Tool Policy. - The server sees one call at a time. It checks each call on its own, with no memory of earlier calls, so it cannot block a sequence of calls that are each allowed.
- A configuration change needs a restart. The server loads its configuration when it starts, and has no reload.
Hook-based checks are one layer of defense. Combine them with the agent’s own permission settings and with sandboxing.