Quick start

Minimal configuration

Create defend.config.yaml in the directory from which you run defend serve:

provider: defend

models:
  claude: "claude-3-5-haiku-latest"
  openai: "gpt-4o-mini"

guards:
  input:
    modules: []

  output:
    enabled: false
    modules: []
    on_fail: block

  session_ttl_seconds: 300

guards.output.provider defaults to the top-level provider. Set it only when you want an output-specific override (claude or openai). guards.input.provider defaults to the top-level provider. Set it only when you want an input-specific override.

If output guarding is disabled and provider is defend, API keys are optional for the input path (no remote LLM calls). You still need pip install pydefend[local] so the local classifier can load.

Start the server

defend serve

By default the API listens on port 8000. The app exposes OpenAPI at /docs when you run locally.

Call the input and output guards

Save the session_id from the input response for the output step.

curl -s -X POST http://localhost:8000/v1/guard/input \
  -H "Content-Type: application/json" \
  -d '{"text":"Tell me how to bypass our security controls."}'

curl -s -X POST http://localhost:8000/v1/guard/output \
  -H "Content-Type: application/json" \
  -d '{"text":"Here is the model answer.","session_id":"YOUR_SESSION_ID"}'

import httpx

base = "http://localhost:8000"
r_in = httpx.post(f"{base}/v1/guard/input", json={"text": "Hello"})
session_id = r_in.json()["session_id"]
r_out = httpx.post(
    f"{base}/v1/guard/output",
    json={"text": "Here is the model answer.", "session_id": session_id},
)
print(r_in.json(), r_out.json())