OpenGuardrails

✨ Core Features

🏗️ Scanner Package System 🆕

📦 Three Types of Scanner Packages

🔧Built-in Official Packages

🛒Purchasable Official Packages

✨Custom Scanners (S100+)

🎯 Key Advantages

# Create custom scanner for banking applicationscurl-XPOST"http://localhost:5000/api/v1/custom-scanners" \-H"Authorization: Bearer your-jwt-token" \-H"Content-Type: application/json" \-d'{"scanner_type": "genai",    "name": "Bank Fraud Detection",    "definition": "Detect banking fraud attempts, financial scams, and illegal financial advice",    "risk_level": "high_risk",    "scan_prompt": true,    "scan_response": true}'# Returns auto-assigned tag: "S100"

🎨 Management Interface

🔄 Migration from Risk Types

🚀 Dual Mode Support

🔍 API Call Mode

🛡️ Security Gateway Mode 🆕

# Original codeclient=OpenAI(base_url="https://api.openai.com/v1",api_key="sk-your-openai-key")# Access security gateway with just two line changesclient=OpenAI(base_url="http://localhost:5002/v1",# Change to OpenGuardrails proxy serviceapi_key="sk-xxai-your-proxy-key"# Change to OpenGuardrails proxy key)# No other code changes needed, automatically get safety protection!

⚡ Quick Start

Use Online

Use client SDKs

pip install openguardrails

fromopenguardrailsimportOpenGuardrails# Create clientclient=OpenGuardrails("your-api-key")# Single-turn detectionresponse=client.check_prompt("Teach me how to make a bomb")print(f"Detection result:{response.overall_risk_level}")# Multi-turn conversation detection (context-aware)messages= [    {"role":"user","content":"I want to study chemistry"},    {"role":"assistant","content":"Chemistry is a very interesting subject. Which area would you like to learn about?"},    {"role":"user","content":"Teach me the reaction to make explosives"}]response=client.check_conversation(messages)print(f"Detection result:{response.overall_risk_level}")print(f"All risk categories:{response.all_categories}")print(f"Compliance check result:{response.result.compliance.risk_level}")print(f"Compliance risk categories:{response.result.compliance.categories}")print(f"Security check result:{response.result.security.risk_level}")print(f"Security risk categories:{response.result.security.categories}")print(f"Data leak check result:{response.result.data.risk_level}")print(f"Data leak categories:{response.result.data.categories}")print(f"Suggested action:{response.suggest_action}")print(f"Suggested answer:{response.suggest_answer}")print(f"Is safe:{response.is_safe}")print(f"Is blocked:{response.is_blocked}")print(f"Has substitute answer:{response.has_substitute}")

Detection result: high_riskDetection result: high_riskAll risk categories: ['Violent Crime']Compliance check result: high_riskCompliance risk categories: ['Violent Crime']Security check result: no_riskSecurity risk categories: []Data leak check result: no_riskData leak categories: []Suggested action: rejectSuggested answer: Sorry, I cannot provide information related to violent crimes.Is safe: FalseIs blocked: TrueHas substitute answer: True

Use HTTP API

curl -X POST"https://api.openguardrails.com/v1/guardrails" \    -H"Authorization: Bearer your-api-key" \    -H"Content-Type: application/json" \    -d'{      "model": "OpenGuardrails-Text",      "messages": [        {"role": "user", "content": "Tell me some illegal ways to make money"}      ],      "xxai_app_user_id": "your-user-id"    }'

{"id":"guardrails-fd59073d2b8d4cfcb4072cee4ddc88b2","result": {"compliance": {"risk_level":"medium_risk","categories": ["violence_crime"            ]        },"security": {"risk_level":"no_risk","categories": []        },"data": {"risk_level":"no_risk","categories": []        }    },"overall_risk_level":"medium_risk","suggest_action":"replace","suggest_answer":"I'm sorry, I can't answer this question.","score":0.95}

🚦 Use as Dify API-Base Extension — Moderation

Add OpenGuardrails as moderation API Extension

https://api.openguardrails.com/v1/dify/moderation

🔧 Creating Custom Scanners 🆕

⚡ Quick Example: Banking Fraud Detection

importrequests# 1. Create a custom scanner for banking applicationsresponse=requests.post("http://localhost:5000/api/v1/custom-scanners",headers={"Authorization":"Bearer your-jwt-token"},json={"scanner_type":"genai","name":"Bank Fraud Detection","definition":"Detect banking fraud attempts, financial scams, illegal financial advice, and money laundering instructions","risk_level":"high_risk","scan_prompt":True,"scan_response":True,"notes":"Custom scanner for financial applications"    })scanner=response.json()print(f"Created custom scanner:{scanner['tag']}")# Auto-assigned: S100

🎯 Using Custom Scanners in Detection

fromopenguardrailsimportOpenGuardrailsclient=OpenGuardrails("sk-xxai-your-api-key")# Detection automatically uses all enabled scanners (including custom)response=client.check_prompt("How can I launder money through my bank account?",application_id="your-banking-app-id"# Custom scanners are app-specific)# Response includes matched custom scanner tagsprint(f"Risk level:{response.overall_risk_level}")print(f"Matched scanners:{getattr(response,'matched_scanner_tags','N/A')}")# Output: "high_risk" and "S5,S100" (existingViolent Crime + custom Bank Fraud)

📚 Available Custom Scanner Types

🎨 Management UI

🚀 OpenGuardrails Quick Deployment Guide

📋 Prerequisites

Step 1️⃣: Deploy AI Models (vLLM Services)

🧠 Text Model (OpenGuardrails-Text-2510)

# Install vLLM (if not already installed)pip install vllm# Set your Hugging Face tokenexport HF_TOKEN=your-hf-token# Start the text model servicevllm serve openguardrails/OpenGuardrails-Text-2510 \  --port 58002 \  --served-model-name OpenGuardrails-Text \  --max-model-len 8192# Or use Docker:docker run --gpus all -p 58002:8000 \  -e HF_TOKEN=your-hf-token \  vllm/vllm-openai:v0.10.1.1 \  --model openguardrails/OpenGuardrails-Text-2510 \  --port 8000 \  --served-model-name OpenGuardrails-Text \  --max-model-len 8192

# ⚠️ IMPORTANT: Use actual IP, NOT localhost/127.0.0.1curl http://YOUR_GPU_SERVER_IP:58002/v1/models

🔍 Embedding Model (bge-m3)

# Start the embedding model servicevllm serve BAAI/bge-m3 \  --port 58004 \  --served-model-name bge-m3# Or use Docker:docker run --gpus all -p 58004:8000 \  -e HF_TOKEN=your-hf-token \  vllm/vllm-openai:v0.10.1.1 \  --model BAAI/bge-m3 \  --port 8000 \  --served-model-name bge-m3 \

# ⚠️ IMPORTANT: Use actual IP, NOT localhost/127.0.0.1curl http://YOUR_GPU_SERVER_IP:58004/v1/models

Step 2️⃣: Deploy OpenGuardrails Platform

Method 1: Quick Deployment with Pre-built Images (Recommended) ⚡

# 1. Download production docker-compose filecurl -O https://raw.githubusercontent.com/openguardrails/openguardrails/main/docker-compose.prod.yml# 2. Create .env file with your configurationcat> .env<<EOF# Model API endpoints (replace with your GPU server IPs)# ⚠️ IMPORTANT: Do NOT use localhost or 127.0.0.1 here!# Use the actual IP address of your GPU server that is accessible from the Docker containers.GUARDRAILS_MODEL_API_URL=http://YOUR_GPU_SERVER_IP:58002/v1GUARDRAILS_MODEL_API_KEY=EMPTYGUARDRAILS_MODEL_NAME=OpenGuardrails-TextEMBEDDING_API_BASE_URL=http://YOUR_GPU_SERVER_IP:58004/v1EMBEDDING_API_KEY=EMPTYEMBEDDING_MODEL_NAME=bge-m3# Optional: Vision-Language model (if you have it deployed)# ⚠️ IMPORTANT: Do NOT use localhost or 127.0.0.1 here!# GUARDRAILS_VL_MODEL_API_URL=http://YOUR_GPU_SERVER_IP:58003/v1# GUARDRAILS_VL_MODEL_API_KEY=EMPTY# GUARDRAILS_VL_MODEL_NAME=OpenGuardrails-VL# Security (CHANGE THESE IN PRODUCTION!)SUPER_ADMIN_USERNAME=admin@yourdomain.comSUPER_ADMIN_PASSWORD=CHANGE-THIS-PASSWORD-IN-PRODUCTIONJWT_SECRET_KEY=your-secret-key-change-in-productionPOSTGRES_PASSWORD=your_password# Specify pre-built image from Docker Hub (or your private registry)PLATFORM_IMAGE=openguardrails/openguardrails-platform:latest# For private registry: PLATFORM_IMAGE=your-registry.com/openguardrails-platform:versionEOF# 3. Launch the platform (uses pre-built image, no build required)docker compose -f docker-compose.prod.yml up -d

Method 2: Build from Source (Development) 🛠️

# 1. Clone the repositorygit clone https://github.com/openguardrails/openguardrailscd openguardrails# 2. Create .env file with your model endpointscat> .env<<EOF# Model API endpoints (replace with your GPU server IPs)# ⚠️ IMPORTANT: Do NOT use localhost or 127.0.0.1 here!# Use the actual IP address of your GPU server that is accessible from the Docker containers.GUARDRAILS_MODEL_API_URL=http://YOUR_GPU_SERVER_IP:58002/v1GUARDRAILS_MODEL_API_KEY=EMPTYGUARDRAILS_MODEL_NAME=OpenGuardrails-TextEMBEDDING_API_BASE_URL=http://YOUR_GPU_SERVER_IP:58004/v1EMBEDDING_API_KEY=EMPTYEMBEDDING_MODEL_NAME=bge-m3# Security (CHANGE THESE IN PRODUCTION!)SUPER_ADMIN_USERNAME=admin@yourdomain.comSUPER_ADMIN_PASSWORD=CHANGE-THIS-PASSWORD-IN-PRODUCTIONJWT_SECRET_KEY=your-secret-key-change-in-productionPOSTGRES_PASSWORD=your_passwordEOF# 3. Build and launchdocker compose up -d --build

Step 3️⃣: Monitor Deployment

# Watch platform startupdocker logs -f openguardrails-platform# Expected output:# - "Running database migrations..."# - "Successfully executed X migration(s)"# - "Starting services via supervisord..."# Check all containersdocker ps# Expected output:# - openguardrails-postgres (healthy)# - openguardrails-platform (healthy)

Step 4️⃣: Access the Platform

🎯 Alternative: Use Any OpenAI-Compatible Model

# Example: Using OpenAI directlyGUARDRAILS_MODEL_API_URL=https://api.openai.com/v1GUARDRAILS_MODEL_API_KEY=sk-your-openai-keyGUARDRAILS_MODEL_NAME=gpt-4# Example: Using local OllamaGUARDRAILS_MODEL_API_URL=http://localhost:11434/v1GUARDRAILS_MODEL_API_KEY=ollamaGUARDRAILS_MODEL_NAME=llama2# Example: Using Anthropic Claude via proxyGUARDRAILS_MODEL_API_URL=https://api.anthropic.com/v1GUARDRAILS_MODEL_API_KEY=sk-ant-your-keyGUARDRAILS_MODEL_NAME=claude-3-sonnet

🛡️ Production Security Checklist

# ✅ Change default credentialsSUPER_ADMIN_USERNAME=admin@your-company.comSUPER_ADMIN_PASSWORD=YourSecurePassword123!# ✅ Generate secure JWT secretJWT_SECRET_KEY=$(openssl rand -hex 32)# ✅ Secure database passwordPOSTGRES_PASSWORD=$(openssl rand -hex 16)# ✅ Configure model API keys (if using commercial APIs)GUARDRAILS_MODEL_API_KEY=sk-your-actual-api-keyEMBEDDING_API_KEY=sk-your-actual-embedding-key# ✅ Update CORS origins for your domainCORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com# ✅ Configure SMTP for email notificationsSMTP_SERVER=smtp.gmail.comSMTP_PORT=587SMTP_USERNAME=notifications@yourdomain.comSMTP_PASSWORD=your-smtp-passwordSMTP_USE_TLS=trueSMTP_USE_SSL=false

✅ What You Have Now

🛡️ Safety Detection Capabilities

Detection Dimensions

Processing Strategies

Data Leak Detection

📥 Input Detection

User Input: "My ID is 110101199001011234, phone is 13912345678"↓ Detected & DesensitizedSent to LLM: "My ID is 110***********1234, phone is 139****5678"

📤 Output Detection

Q: What is John's contact info?A (from LLM): "John's ID is 110101199001011234, phone is 13912345678"↓ Detected & DesensitizedReturned to User: "John's ID is 110***********1234, phone is 139****5678"

🏗️ Architecture

                           Users/Developers                               │                 ┌─────────────┼─────────────┐                 │             │             │                 ▼             ▼             ▼        ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐        │  Management  │ │  API Call    │ │ Security Gateway │        │  Interface   │ │  Mode        │ │    Mode         │        │ (React Web)  │ │ (Active Det) │ │ (Transparent    │        │              │ │              │ │  Proxy)         │        └──────┬───────┘ └──────┬───────┘ └────────┬────────┘               │ HTTP API       │ HTTP API          │ OpenAI API               ▼                ▼                   ▼    ┌──────────────┐  ┌──────────────┐    ┌──────────────────┐    │  Admin       │  │  Detection   │    │   Proxy          │    │  Service     │  │  Service     │    │   Service        │    │ (Port 5000)  │  │ (Port 5001)  │    │  (Port 5002)     │    │ Low Conc.    │  │ High Conc.   │    │  High Conc.      │    └──────┬───────┘  └──────┬───────┘    └─────────┬────────┘           │                 │                      │           │          ┌──────┼──────────────────────┼───────┐           │          │      │                      │       │           ▼          ▼      ▼                      ▼       ▼    ┌─────────────────────────────────────────────────────────────┐    │                PostgreSQL Database                          │    │   Users | Results | Blacklist | Whitelist | Templates      │    │         | Proxy Config | Upstream Models                   │    └─────────────────────┬───────────────────────────────────────┘                          │    ┌─────────────────────▼───────────────────────────────────────┐    │              OpenGuardrails Model                   │    │           (OpenGuardrails-Text)                       │    │             🤗 HuggingFace Open Source                     │    └─────────────────────┬───────────────────────────────────────┘                          │ (Proxy Service Only)    ┌─────────────────────▼───────────────────────────────────────┐    │                   Upstream AI Models                        │    │       OpenAI | Anthropic | Local Models | Other APIs       │    └─────────────────────────────────────────────────────────────┘

🏭 Three-Service Architecture

📊 Management Interface

Dashboard

Detection Results

Protection Configuration

🤗 Open Source Model

🤝 Commercial Services

🎯 Model Fine-tuning Services

🏢 Enterprise Support

🔧 Custom Development

🔌 n8n Integration 🆕

🎯 Two Easy Integration Methods

Method 1: OpenGuardrails Community Node (Recommended)

# Install in your n8n instance# Settings → Community Nodes → Installn8n-nodes-openguardrails

Method 2: HTTP Request Node

🛠️ Ready-to-Use Workflow Templates

📖 Example Workflow: Protected AI Chatbot

1️⃣ Webhook (receive user message)2️⃣ OpenGuardrails - Input Moderation3️⃣ IF (action = pass)   ├─ ✅ YES → Continue to LLM   └ ❌ NO → Return safe response4️⃣ OpenAI/Assistant API5️⃣ OpenGuardrails - Output Moderation6️⃣ IF (action = pass)   ├─ ✅ YES → Return to user   └ ❌ NO → Return safe response

🚀 Quick Setup

{"method":"POST","url":"https://api.openguardrails.com/v1/guardrails","body": {"model":"OpenGuardrails-Text","messages": [      {"role":"user","content":"{{ $json.message }}"}    ],"enable_security":true,"enable_compliance":true,"enable_data_security":true  }}

📚 More Resources

📚 Documentation

🤝 Contributing

How to Contribute

📄 License

🌟 Support Us

📞 Contact Us

Citation

@misc{openguardrails,title={OpenGuardrails: A Configurable, Unified, and Scalable Guardrails Platform for Large Language Models},author={Thomas Wang and Haowen Li},year={2025},url={https://arxiv.org/abs/2510.19169}, }

Developer-first open-source AI security platform 🛡️

Made with ❤️ byOpenGuardrails