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

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 lines 225-232. Ensure you install the cosmos_guardrail package alongside the core Diffusers library:

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:

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:

# 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:

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:

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 lines 108-122 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:

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 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 lines 225-232.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}