# How to Set Up the Guardrail Safety Checker for Cosmos 3 Generator

> Learn to set up the Guardrail safety checker for the NVIDIA Cosmos 3 Generator. Easily enable or disable this essential feature for secure AI model generation.

- Repository: [NVIDIA Corporation/cosmos](https://github.com/NVIDIA/cosmos)
- Tags: how-to-guide
- Published: 2026-07-03

---

**The Cosmos 3 Generator guardrail safety checker is implemented via the `cosmos_guardrail` package and can be toggled via `enable_safety_checker=False` in Diffusers, `"guardrails": false` in the `extra_params` JSON field for vLLM-Omni, or the `--no-guardrails` flag in the Cosmos Framework CLI.**

The NVIDIA/cosmos repository provides a dedicated safety layer for the **Cosmos 3 Generator** surface—a multimodal capable of producing images, video, audio, and action trajectories. The **guardrail** system consists of lightweight models that automatically load when you install the `cosmos_guardrail` package, screening input prompts and blurring faces in generated media. This guide covers how to set up and configure the guardrail safety checker for Cosmos 3 Generator across the three primary integration levels: Diffusers, vLLM-Omni, and the Cosmos Framework CLI.

## Installing the Guardrail Package

The guardrail models are automatically installed as a dependency when you follow the Diffusers quick-start instructions in the repository's [`README.md`](https://github.com/NVIDIA/cosmos/blob/main/README.md) [`lines 225-232`](https://github.com/NVIDIA/cosmos/blob/main/README.md#L225-L232). Ensure you install the `cosmos_guardrail` package alongside the core Diffusers library:

```bash
uv pip install --torch-backend=auto \
  "diffusers @ git+https://github.com/huggingface/diffusers.git" \
  cosmos_guardrail accelerate av huggingface_hub \
  imageio imageio-ffmpeg torch torchvision transformers

```

Once installed, the `Cosmos3OmniPipeline` automatically initializes the safety checker by default unless explicitly disabled.

## Diffusers (Python) Configuration

The **Diffusers** integration provides the most direct control over the guardrail via the `Cosmos3OmniPipeline` class.

### Enabling Guardrails (Default)

Guardrails are enabled automatically when you load the pipeline. The system screens prompts and processes generated media for faces before returning output:

```python
import torch
from diffusers import Cosmos3OmniPipeline
from diffusers.utils import export_to_video

pipe = Cosmos3OmniPipeline.from_pretrained(
    "nvidia/Cosmos3-Nano",
    torch_dtype=torch.bfloat16,
    device_map="cuda",
)

# Generate with safety checks active

result = pipe(
    prompt="A robot picks up a red ball in a factory.",
    num_frames=189,
    height=720,
    width=1280,
    fps=24,
    num_inference_steps=35,
    guidance_scale=6.0,
    generator=torch.Generator(device="cuda").manual_seed(42),
)

export_to_video(result.video, "output_guardrail.mp4", fps=24)

```

### Disabling Guardrails

To disable the safety checker globally, set the `enable_safety_checker` attribute to `False` after loading the pipeline:

```python

# Disable globally for all subsequent calls

pipe.enable_safety_checker = False

# Or pass per-request (newer versions support a flag)

result = pipe(
    prompt="A robot arm paints a blue canvas.",
    num_frames=189,
    height=720,
    width=1280,
    fps=24,
    guardrails=False  # Per-request override

)

```

For a complete working example, see the notebook at `cookbooks/cosmos3/generator/audiovisual/run_with_diffusers.ipynb` in the repository.

## vLLM-Omni (OpenAI-Compatible API) Configuration

The **vLLM-Omni** server enables guardrails by default in the container image. You can toggle them via the `extra_params` JSON field without restarting the server.

### Starting the Server

Launch the server with guardrails enabled by default:

```bash
docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -v "$(pwd):/workspace" -p 8000:8000 --ipc=host \
  vllm/vllm-omni:cosmos3 \
  vllm serve nvidia/Cosmos3-Nano \
  --omni \
  --model-class-name Cosmos3OmniDiffusersPipeline \
  --port 8000 \
  --init-timeout 1800

```

### Disabling Guardrails Per Request

Send a request with the `guardrails` key set to `false` in the `extra_params` field:

```bash
curl -sS -X POST http://localhost:8000/v1/videos/sync \
  --form-string "prompt=A drone flies over a city at sunset." \
  --form-string "size=1280x720" \
  --form-string "num_frames=189" \
  --form-string "fps=24" \
  --form-string "num_inference_steps=35" \
  --form-string "guidance_scale=6.0" \
  --form-string 'extra_params={"guardrails":false,"use_resolution_template":false,"use_duration_template":false}' \
  -o cosmos3_no_guardrail.mp4

```

### Disabling Guardrails Server-Wide

To disable guardrails for all requests, create a deployment configuration file following the example in [`README.md`](https://github.com/NVIDIA/cosmos/blob/main/README.md) [`lines 108-122`](https://github.com/NVIDIA/cosmos/blob/main/README.md#L108-L122) and launch the server with `--deploy-config no_guardrails.yaml`.

## Cosmos Framework (CLI) Configuration

The **Cosmos Framework** provides a command-line interface that wraps the same Diffusers pipeline used in the Python integration.

### Running with Guardrails Disabled

Use the `cosmos_framework inference` command with the `--extra-params` flag containing the JSON configuration:

```bash
cosmos_framework inference \
  --model-id nvidia/Cosmos3-Nano \
  --prompt "A drone flies over a city at sunset." \
  --extra-params '{"guardrails":false,"use_resolution_template":false}' \
  --output output_no_guardrail.mp4

```

The framework reads the same `extra_params` JSON field used by the vLLM-Omni server, ensuring consistent behavior across both runtimes. A future release will support the `--no-guardrails` flag for direct command-line toggling.

Reference implementations are available in `cookbooks/cosmos3/generator/audiovisual/run_with_cosmos_framework.ipynb` and `cookbooks/cosmos3/generator/audiovisual/run_with_vllm_omni.ipynb`.

## Summary

- The **Guardrail safety checker** for Cosmos 3 Generator is packaged as `cosmos_guardrail` and automatically loads with the Diffusers pipeline.
- In **Diffusers**, set `pipe.enable_safety_checker = False` to disable globally, or pass `guardrails=False` per request.
- In **vLLM-Omni**, include `"guardrails": false` in the `extra_params` JSON field, or use a deployment config for server-wide disable.
- In **Cosmos Framework**, pass `'{"guardrails":false}'` to the `--extra-params` flag.
- Installation instructions and configuration examples are located in [`README.md`](https://github.com/NVIDIA/cosmos/blob/main/README.md) and the `cookbooks/cosmos3/generator/audiovisual/` directory.

## Frequently Asked Questions

### What content does the Cosmos 3 guardrail safety checker actually filter?

The guardrail screens input prompts for safety and post-processes generated media to blur faces in images, video, and audio outputs. These lightweight models run automatically during the generation pipeline to ensure responsible AI usage.

### Can I disable guardrails for a single request without affecting the server configuration?

Yes. In the vLLM-Omni API, include `"guardrails": false` in the `extra_params` field of your request payload. In Diffusers, newer versions support passing `guardrails=False` directly to the pipeline call. This allows you to bypass safety checks for individual generations while keeping the default protection enabled for other requests.

### Where are the guardrail models loaded from in the Cosmos 3 Generator?

The guardrail models are automatically downloaded and cached via the Hugging Face Hub when you install the `cosmos_guardrail` package. The `Cosmos3OmniPipeline` handles model initialization and device placement according to your `device_map` configuration, as documented in [`README.md`](https://github.com/NVIDIA/cosmos/blob/main/README.md) [`lines 225-232`](https://github.com/NVIDIA/cosmos/blob/main/README.md#L225-L232).

### Is the guardrail available for the Cosmos 3 Reasoner surface?

No. According to the NVIDIA/cosmos source code, guardrails are specifically implemented for the **Generator** surface, which produces multimodal outputs like images and video. The **Reasoner** surface is text-only and does not include the `cosmos_guardrail` safety layer.