Skip to main content
Point Custom Guardrails directly at Onyx AI Guard. No adapter or FastAPI wrapper is required — Onyx speaks the TrueFoundry custom-guardrail contract on a dedicated /truefoundry endpoint.

​
What is Onyx Security?

Onyx AI Guard evaluates LLM prompts and responses against policies you configure in the Onyx console (prompt protection, content moderation, keywords, sensitive data, and more). TrueFoundry calls Onyx on the llm_input and llm_output hooks and enforces the returned verdict.

​
How it works

  1. Build the evaluate URL from your AI Guard policy:
    The Guard Token in the path is the auth to Onyx (leave Auth Data empty in the dashboard). Use your tenant hostname — bare https://ai-guard.onyx.security is not routed and returns 404.
  2. Register two Custom Guardrail configs (input + output) that both use that same URL.
  3. TrueFoundry POSTs its standard custom-guardrail body. Presence of responseBody selects output evaluation.
  4. Onyx returns HTTP 200 with {"verdict": true} or {"verdict": false, "message": "..."}. Mask/ask map to a block verdict on this Validate integration.

​
Response contract

Policy blocks must use 2xx + verdict: false, not HTTP 4xx. See Custom guardrail response contract. Set Enforcing Strategy to Enforce or Enforce But Ignore On Error for block testing. Audit logs violations without blocking. Streamed responses skip output guardrails — use "stream": false when verifying output.

​
Prerequisites

  • TrueFoundry AI Gateway that honors verdict: false on HTTP 200.
  • An Onyx AI Guard policy with at least one Block rule that scans Input and/or Output.
  • Outbound HTTPS from the gateway to your tenant AI Guard host.

​
Setup

1

Get your Guard Token

In Onyx: Policies → Runtime Policies → AI Guard → ⋮ → AI Guard URL. Copy the Guard Token and the tenant hostname.This is not an MCP Gateway Token or an API Keys page credential.
2

Register Custom Guardrail configs

AI Gateway → Guardrails → New Guardrails Group → Custom → group name onyx-security.
3

Attach to traffic

Model pin: AI Gateway → Models → <model> → Guardrails → attach group onyx-security.Per request — X-TFY-GUARDRAILS header, selector format <group>/<config-name>:
4

Verify

Input. Send each blocked keyword as the user message in a separate request (for example bradpitt, fightclub, norton on the Onyx test policy). Under Enforce / Enforce But Ignore On Error, expect HTTP 400 with error.type: guardrail_checks_failed.Output. Attach onyx-output, set "stream": false, and keep the keyword out of the input so the request reaches the model. Ask the model to join spaced letters so the assistant produces the keyword. Expect the response to be blocked.Confirm the violation in Onyx Runtime Alerts and the guardrail result in TrueFoundry Request Traces.Direct curl against Onyx (same body the gateway sends). Include subjectSlug on context.user — without it Onyx returns verdict: false with "Onyx AI Guard could not validate the request":

​
Known limitations

  • Validate only — Mask rules return a block verdict instead of redacting content.
  • No streamed output guarding — set "stream": false for response checks.
  • Direction matters — Input-only rules do not block responses; enable Output scanning on the rule.
  • Text only — latest user message (input) / first assistant message (output); tool/image rules have nothing to evaluate on this path.
The open-source repo integrations/onyx ships a small FastAPI forwarder that POSTs the same TrueFoundry body to /truefoundry. Production should call Onyx directly. Use the forwarder only for local smoke tests (pytest -v tests/ with ONYX_API_KEY + ONYX_API_BASE set).

​
Troubleshooting

​
Reference