Run the Guardrails Server

Prerequisites

Install the server extra, which adds FastAPI and uvicorn:

pip install 'mend-guardrails[server]'

You also need a Mend licence key. Set it as an environment variable:

export MEND_KEY="your-mend-key"

---

Prepare your policies

Create a directory that contains your policy files. Each file becomes an independently addressable guardrail configuration.

policies/
├── default.json       # config_id: "default"
├── strict.json        # config_id: "strict"
└── permissive.json    # config_id: "permissive"

A minimal policy file uses the same JSON format as the inline config dict accepted by MendGuardrailsClient:

{
  "version": 1,
  "pre_flight": {
    "version": 1,
    "guardrails": [
      {
        "name": "PII",
        "config": { "entities": ["EMAIL_ADDRESS", "PHONE_NUMBER"], "block": false }
      }
    ]
  },
  "input": {
    "version": 1,
    "guardrails": [
      { "name": "PromptInjection", "config": { "confidence_threshold": 0.5 } },
      { "name": "HarmfulContent", "config": { "categories": ["hate", "violence"] } }
    ]
  },
  "output": {
    "version": 1,
    "guardrails": [
      { "name": "HarmfulContent", "config": { "categories": ["hate", "violence"] } }
    ]
  }
}

Alternatively, you can use subdirectories — a subdirectory named strict that contains a policy.json file is equivalent to strict.json at the top level:

policies/
└── strict/
    └── policy.json    # config_id: "strict"

---

Start the server

Console script (recommended)

mend-guardrails-server \
  --policy-dir ./policies \
  --default-config default \
  --host 0.0.0.0 \
  --port 8000

Uvicorn directly

MEND_GUARDRAILS_POLICY_DIR=./policies \
MEND_GUARDRAILS_DEFAULT_CONFIG_ID=default \
uvicorn guardrails.server.api:app --host 0.0.0.0 --port 8000

All CLI options

Option	Default	Description
--host	0.0.0.0	Network interface to bind.
--port	8000	TCP port to listen on.
--policy-dir PATH	./policies	Directory containing policy files. Sets MEND_GUARDRAILS_POLICY_DIR.
--default-config ID	(none)	Policy ID used when a request omits guardrails.config_id. Sets MEND_GUARDRAILS_DEFAULT_CONFIG_ID.
--reload	false	Enable uvicorn hot-reload. Development only.
--log-level	info	Uvicorn log level: debug, info, warning, error.

---

Environment variables

All configuration can be supplied via environment variables, making the server container-friendly without any CLI flags.

Variable	Required	Description
MEND_KEY	Yes (unless offline)	Mend licence key.
MEND_GUARDRAILS_OFFLINE	No	Set to true to skip licence validation and remote policy fetch.
MEND_GUARDRAILS_POLICY_DIR	No	Directory containing policy files. Defaults to ./policies.
MEND_GUARDRAILS_DEFAULT_CONFIG_ID	No	Default policy ID when a request omits guardrails.config_id.
OPENAI_API_KEY	Yes (for OpenAI upstream)	Forwarded to the upstream LLM provider.
OPENAI_BASE_URL	No	Override the upstream base URL (e.g. Azure endpoint, local Ollama).

---

Verify the server is running

Once the server starts you should see output similar to:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Check the health endpoint:

curl http://localhost:8000/health

{"status": "ok"}

List your loaded policies:

curl http://localhost:8000/v1/guardrails/configs

[
  {"id": "default"},
  {"id": "strict"},
  {"id": "permissive"}
]

---

Docker

A minimal Dockerfile for the server:

FROM python:3.12-slim

WORKDIR /app

RUN pip install --extra-index-url https://downloads.mend.io/guardrails/ \
    "mend-guardrails[server]"

COPY policies/ ./policies/

ENV MEND_GUARDRAILS_POLICY_DIR=/app/policies
ENV MEND_GUARDRAILS_DEFAULT_CONFIG_ID=default

EXPOSE 8000

CMD ["mend-guardrails-server", "--host", "0.0.0.0", "--port", "8000"]

Build and run:

docker build -t mend-guardrails-server .

docker run \
  -e MEND_KEY="$MEND_KEY" \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  -p 8000:8000 \
  mend-guardrails-server

---

Development mode (hot-reload)

During development, pass --reload to automatically restart the server when source files change:

mend-guardrails-server \
  --policy-dir ./policies \
  --reload \
  --log-level debug

Note: --reload re-instantiates the FastAPI app on each change. Cached guardrail clients are discarded and reloaded on the next request, which means the first request after a reload pays the warm-up cost again. Do not use --reload in production.