Skip to main content
@neuraltrust/n8n-nodes-trustguard is a community node that makes an n8n workflow a TrustGuard collector. It calls /v1/evaluate and routes each item to one of four outputs — Allow, Report, Transform, Block — so the verdict becomes a branch you can see on the canvas rather than a value you have to remember to check. It is a regular app node on the main path. It is not n8n’s built-in Guardrails node, not a LangChain sub-node you attach to the AI Agent, and not an Agent tool gate: the policy lives in your NeuralTrust collector rather than in the workflow, every verdict carries a trace_id that reconciles with Activity, and transform rewrites the payload in flight.

​
Coverage

Ask — a workflow cannot prompt anyone mid-run, so the node applies Block and leaves trustguard.status as ask for you to branch on. From 0.2.0 it no longer fails on it. Use it when you already build AI workflows in n8n and want enforcement to be an explicit edge in the graph. Not when the guarantee has to hold for traffic you do not control — the gate exists only where you wire it, so a second workflow calling a model directly is unguarded. That is a gateway. Limits. Block and redact are conditional because the node routes but does not stop: an item on the Block output that you wire back into the AI Agent is monitoring, not blocking. Tool-level coverage is only what your graph makes explicit — there is no hook inside an AI Agent node’s own loop. Full comparison: Coverage.

​
Before you start

Keep the policy in Report mode for the first rollout. Report downgrades every rule to report, so findings appear in Activity without breaking traffic. Switch to Enforce once the finding volume looks right — see Policies.

​
1. Install the node

In n8n, Settings → Community nodes → Install a community node, and enter:
Or on the host directly:
In queue mode the node has to be installed on every worker, not only the main instance. A worker without it fails the execution rather than skipping the gate, so this is loud rather than silent — but it will take your workflows down.

​
2. Create the credential

Add a NeuralTrust TrustGuard API credential before you add the node, so the node picks it up on first open. Test posts a one-word protocol: all ping to /v1/evaluate. A pass proves the key, the base URL and egress all work — do it now rather than debugging it inside a workflow.

​
3. Gate the input

Add NeuralTrust TrustGuard between the trigger and the AI Agent, with Operation set to Evaluate Input:
On the Block branch, a Chat Trigger workflow wants a Set node emitting output from {{ $json.trustguard.blockedMessage }}; a webhook workflow wants Respond to Webhook with status 403, which webhook-403.json works through. Input Mode decides what gets sent: The role matters: an Output-phase rule scoped to assistant, or an indirect-injection rule scoped to tool, only fires if the message carries that role. Text prefills {{ $json.chatInput }} on Evaluate Input and {{ $json.output }} on Evaluate Output; Messages prefills {{ $json.messages }} and accepts either a literal JSON array typed into the field or an expression that resolves to one — n8n does not parse a json parameter for a node, so the node does it itself.
If the Text expression resolves to empty or undefined, the node fails closed instead of evaluating an empty payload. The default {{ $json.output }} against a node that emits text resolves to nothing, and an empty payload scores allow. Failing the item is the only safe answer, because the alternative is a green Allow branch over content that was never read.

​
4. Scan the output

Add a second node after the AI Agent with Operation set to Evaluate Output. It sends direction: output, so your Output-phase rules apply, and it prefills {{ $json.output }}. The node runs on a complete item, so an output-side block lands before the item reaches whatever answers the user — unless the workflow already streamed the response, in which case the tokens have gone and the verdict is detection after the fact.

​
5. Know how each verdict lands

Only allow and skip reach Allow. Anything else reaches Block, so a verdict a future TrustGuard release adds is denied rather than forwarded while you wait for a node update. guardrailsInput is the field the node writes the evaluated text to, on every branch: the masked text on Transform, Blocked by NeuralTrust TrustGuard. trace_id=… on Block and on ask, and the original text otherwise. It is the field to read downstream.
On Block and Report the node rewrites nothing but guardrailsInput, and in Messages mode a transform never touches chatInput. Anything reading chatInput or messages — including an AI Agent in auto prompt mode — therefore gets the original, unmasked prompt. Read guardrailsInput on any branch you wire back into the agent.
Alongside the verdict the node writes a trustguard object onto the item:
findings is copied from the response for every verdict that carries them, not only report. workflowId, workflowName and executionId are output metadata only — they are never sent in the evaluate body, because /v1/evaluate rejects unknown top-level keys with a 400.
Wiring several outputs into one downstream node makes that node execute once per connected output. To tally verdicts in one place, put a Merge node in between and set it to the number of inputs you connect.

​
6. Set the options

Options is an n8n collection, so an option you have not added is not sent at all — the Default column below is what the field prefills with once you click Add option. collector_key, consumer_id, session_id and attributes.model.provider are sent only when set. protocol, attributes.content_type and attributes.model.name are always sent, the last as an empty string when Model Name is blank. Add Session ID and keep its prefilled {{ $json.sessionId }}: leave the option off and TrustGuard synthesises a session per request, so Activity cannot group turns the way your chat does. Add Consumer ID if the collector has per-consumer policy overrides, or every request resolves to the default policy — in a chat workflow the natural source is the trigger’s authenticated user. Protocol should stay llm for chat workflows.

​
7. Choose fail-open or fail-closed

The node fails closed by default, and Fail Open on Unreachable is deliberately narrow. It covers only connect errors, timeouts, HTTP 502/504, and HTTP 429 after retries are exhausted. Those are retried first: three attempts in total. An HTTP retry honours Retry-After up to 5s; a transport error has no header to read, so it always backs off 0.25s then 0.5s. Everything else fails closed even with fail-open on:
  • HTTP 401/403, and 503 entitlement failures
  • any other 4xx/5xx
  • a non-JSON 200, or a verdict this version of the node does not recognise
  • a transformed_payload that cannot be applied safely
  • an empty or unresolved Text expression
  • TLS and certificate failures — an untrusted certificate looks like a connect error, but it is a configuration fault rather than an outage, so fail-open does not cover it. A corporate MITM proxy without a trusted CA will therefore fail every item.
The transformed_payload case matters more than it looks. If a transform comes back misaligned — a different message count, a changed role, a rewritten tool name or id, a non-text content part — the node refuses it and fails closed rather than applying a partial redaction. Silently forwarding a half-masked prompt while the console shows a successful transform is the worst available outcome, so it is not an option.
Transport failures are classified from the error code on the cause chain (ECONNREFUSED, ENOTFOUND, ETIMEDOUT, …) as well as from the message text, because n8n rewrites those codes into prose before a node ever sees them.

​
On Error

Fail Open on Unreachable is scoped to transport failures. n8n’s own Settings → On Error is not, and it is the setting most likely to open a hole by accident: No On Error setting can put an unevaluated item on Allow. Failures route to Block, which n8n still relocates to the error output when that mode is selected. Filter on trustguard.evaluated === false to find every item that reached a branch without being evaluated — it is set both on a fail-open Allow item and on a Block-routed failure.

​
8. Verify

With a jailbreak rule in Enforce mode, run the workflow with:
The item should leave on Block and the AI Agent should never run. trustguard.trace_id on the blocked item is the same identifier the finding carries in Activity, so use it to reconcile a run with what the console shows. Then check the inverse — an ordinary prompt leaves on Allow and reaches the agent.

​
As an AI Agent tool

The node sets usableAsTool, so n8n also offers it as a tool an AI Agent can call. That path is built for reporting, not enforcement.
As a tool the four outputs do not exist. n8n’s tool wrapper reads only the first output, so every verdict — including block — is returned there instead, which is what keeps a block from arriving at the agent as an empty result that reads as “nothing wrong”. The verdict is therefore visible to the model, not enforced: a model can decline to call a tool, or call it and ignore the answer. Put the node on the main path for anything you need to guarantee.

​
Templates

If you can install the node, examples/ holds nine importable workflows covering every operation, option, output and failure mode — start with 01-input-gate-four-verdicts.json. For instances where installing a community node is not an option, the node repository also ships three workflows built from HTTP Request + Switch that call the same endpoint: Attach a Header Auth credential (Authorization: Bearer tgk_…) after importing. Never paste a key into the workflow JSON — it is stored unencrypted and travels with every export.

​
Limits to keep in mind

  • The gate is only where you wire it. Even inside a guarded workflow, a branch that routes around the node is unguarded.
  • Each guarded direction is one round trip, and the node evaluates items one at a time — a batch of 50 items is 50 calls. Timeout is per attempt, so a 5s timeout over three attempts can hold an execution open for more than 15s before the item fails.
  • Transform rewrites text and tool-call arguments only. Tool name and call id values are checked against the request and never changed, a transformed tool call is re-emitted in OpenAI {id, type, function} form, a call that arrived without an id cannot be transformed at all, and a non-text content part cannot be masked — those refuse and fail closed rather than partially applying.
  • There is no hook inside the AI Agent loop. n8n does not expose one, so a tool call cannot be gated before it executes the way the LangChain middleware gates one. Route tool traffic through TrustGate where that matters.
Full contract for the endpoint behind all of this: Evaluate API. Source and issues: NeuralTrust/n8n-nodes-trustguard.