> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fireworks Safety Model Guardrail for TrueFoundry AI Gateway

> Use Fireworks-hosted safety models (gpt-oss-safeguard with your policy, or Llama Guard) as a TrueFoundry AI Gateway guardrail for prompts and responses.

This guide explains how to use a safety model hosted on [Fireworks](https://fireworks.ai) as a guardrail in the TrueFoundry AI Gateway. The gateway sends each guarded prompt or response to your Fireworks safety model through the [Fireworks chat completions API](https://docs.fireworks.ai/api-reference/post-chatcompletions) and enforces the model's verdict.

## How the integration works

Two model types are supported:

* **gpt-oss-safeguard** classifies content against a policy you write. The policy goes in the system message, the content to classify goes in the user message, and the guardrail adds an instruction asking for a JSON verdict (`{"violation": 0 or 1, "policy_category": ...}`), so do not ask for another answer format in the policy.
* **Llama Guard** classifies content against Meta's fixed hazard categories. The model answers `safe`, or `unsafe` followed by the violated category codes. The policy field is ignored.

The guardrail runs as a **Validate**-only guardrail: content is classified and can be blocked, but it is never rewritten or redacted.

| Hook | What is sent to Fireworks |
| - | - |
| LLM input | The request messages, without the application's system prompt |
| LLM output | The request messages as context, and the model response as the content to classify |
| MCP pre-tool | The tool call arguments |
| MCP post-tool | The tool result |

| Model reply | Result |
| - | - |
| Safe (`0`, `safe`) | The request continues |
| Any violation (`1`, `unsafe`), even next to a safe verdict | A violation, handled by your [enforcing strategy](#enforcing-strategy) |
| No readable verdict (a refusal, prose, a truncated answer) | A guardrail error, never a pass. See [Enforcing strategy](#enforcing-strategy) |

## Prerequisites

* A Fireworks API key.
* A safety model running on a Fireworks **on-demand (dedicated) deployment**. See the [Fireworks on-demand deployment guide](https://docs.fireworks.ai/getting-started/ondemand-quickstart) to create one.
* A deployment that stays running. Fireworks returns a 503 while a deployment scaled to zero starts up and does not queue requests, so set the deployment's minimum replicas to at least 1 (or turn scale-to-zero off). See [Fireworks autoscaling](https://docs.fireworks.ai/deployments/autoscaling).
* Network access from the AI Gateway to `api.fireworks.ai`.

## Add the Fireworks guardrail

<Steps>
  <Step title="Pick Fireworks from the guardrail registry">
    From **AI Gateway → Guardrails → Registry**, select **Fireworks** under **External Providers**. See [Get started with guardrails](/docs/ai-gateway/guardrails-getting-started) for the end-to-end flow of adding any guardrail.
  </Step>

  <Step title="Fill in the Fireworks form">
    | Field | Required | Description |
    | - | :-: | - |
    | **Name** | ✅ | Identifier for this guardrail (for example, `fireworks-safeguard`). Used when you reference the guardrail from rules. |
    | **Description** | | Free-form description shown in the dashboard. |
    | **Auth Data → API Key** | ✅ | Fireworks API key. Stored encrypted and sent as a Bearer token. |
    | **Model** | ✅ | The deployment name from your Fireworks account, `accounts/<account>/deployments/<deployment>`. |
    | **Model Type** | ✅ | `gpt-oss-safeguard` (default) or `llama-guard`. |
    | **Policy** | For `gpt-oss-safeguard` | The safety policy the model applies. Describe what violates and what is safe, with examples. It is ignored for `llama-guard`. Do not put secrets in the policy. |
    | **Operation** | ✅ | `Validate` only. |
    | **Enforcing Strategy** | ✅ | See [Enforcing strategy](#enforcing-strategy). |

    <Warning>
      A `gpt-oss-safeguard` guardrail without a policy fails every request with a guardrail error, because there is nothing for the model to apply.
    </Warning>
  </Step>

  <Step title="Bind the guardrail to models with a rule">
    Attach the guardrail through a **Guardrail Rule** on the hooks you want: `llm_input_guardrails`, `llm_output_guardrails`, `mcp_tool_pre_invoke_guardrails` and `mcp_tool_post_invoke_guardrails`. See [Guardrails Configuration](/docs/ai-gateway/guardrails-configuration) for the full policy reference.
  </Step>
</Steps>

## Enforcing strategy

| Strategy | Violation | Fireworks unreachable, times out, or returns no readable verdict |
| - | - | - |
| **Enforce** | Request rejected | Request rejected |
| **Enforce But Ignore On Error** | Request rejected | Request continues |
| **Audit** | Recorded, request continues | Request continues |

Use **Enforce** for a guardrail that must not fail open.

<Warning>
  Validate guardrails run in parallel with the model request, so a prompt that is later rejected has already reached the model. To run guardrails before the model, turn off **Run Guardrails in Parallel with Model Request** in the gateway guardrail settings.
</Warning>

## Verify the integration

Select the guardrail on a request with the `X-TFY-GUARDRAILS` header, using the `<group>/<guardrail-name>` selector:

```bash theme={"dark"}
curl https://<your-gateway-url>/chat/completions \
  -H "Authorization: Bearer ${TFY_API_KEY}" \
  -H "Content-Type: application/json" \
  -H 'X-TFY-GUARDRAILS: {"llm_input_guardrails":["my-group/fireworks-safeguard"]}' \
  -d '{"model":"<your-model>","messages":[{"role":"user","content":"Hello"}]}'
```

A rejected request carries a category-only message, for example `Fireworks safety model policy violation (categories: hate speech)`. For `gpt-oss-safeguard` the category is shown only when it matches a line of your policy, and for Llama Guard it is the category name for the returned code. The message never includes the content, the model's reasoning or the policy. You can inspect the full guardrail evaluation in **AI Gateway → Monitor → Request Traces**.

## Limits

* Output inspection is skipped for streamed responses.
* Only text is classified. A request that is only an image or file, and a completion that is only tool calls, have nothing to classify, so no Fireworks call is made and the request passes.
* At most 120,000 characters are sent per call. The content being classified must fit, otherwise the call is a guardrail error handled by your enforcing strategy; use the [`x-tfy-guardrails-scope` request header](/docs/ai-gateway/request-headers) to classify fewer messages in a long conversation. On the output hook the conversation context is trimmed, oldest first, to fit.
* The guardrail timeout is the gateway-wide guardrail timeout, 5 seconds by default, and it is not configured per guardrail. The guardrail asks the model for low reasoning effort. A timeout is a guardrail error, so raise the gateway guardrail timeout if your model needs longer.
* Llama Guard judges only the final turn of the conversation it is given, so when several messages are classified the guardrail folds them all into that final turn. An MCP tool result is sent as a user message, because Llama Guard conversations start with a user turn.

## Reference

* [Fireworks chat completions API](https://docs.fireworks.ai/api-reference/post-chatcompletions)
* [Fireworks on-demand deployments](https://docs.fireworks.ai/getting-started/ondemand-quickstart)
* [TrueFoundry guardrails overview](/docs/ai-gateway/guardrails-overview)
* [Get started with guardrails](/docs/ai-gateway/guardrails-getting-started)
* [Configure guardrail policies](/docs/ai-gateway/guardrails-configuration)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.