Name: openguardrails
Author: openguardrails

OpenGuardrails

The vendor-neutral protocol for AI agent safety & security — and the neutral benchmark that ranks the vendors.

Integrate safety & security once, enforce it across every agent, sandbox, and LLM — instead of wiring every vendor to every tool by hand.

Apache-2.0 · openguardrails.com

This monorepo is the home of the OpenGuardrails (OGR) specification and its reference implementations. The specification is the normative contract every adapter, detector, and sandbox speaks; the core runtimes, integrations, benchmark, examples, skill, and website live alongside it so changes can be reviewed and tested together.

OGR is not a guardrail product: it defines the wire and referees the leaderboard. Vendors compete on detection quality behind a common plug; users get one way to configure and compose safety & security across every agent they run.

We define the wire — events, verdicts, provenance, correlation, composition.
We referee the benchmark.
We do not build detection capability — vendors compete behind the contract.

   agent adapters            LLM-protocol adapters
  (hermes, openclaw,        (openai.chat, openai.responses,
   claude-code, codex,       anthropic.messages)
   opencode, kilocode)
        │                          │
        ▼                          ▼
   ┌───────────────────────────────────────────┐
   │  OGR core contract                        │
   │  GuardEvent · Verdict · Provenance ·      │
   │  guard-context · composition · taxonomy   │
   └───────────────────────────────────────────┘
        ▲                          ▲
        │                          │
   detector plugins           sandbox adapters
  (config rules OR           (srt, openshell —
   model/classifier)          runtime PEP + policy compile)

Why a standard

Without OGR, securing an agent is an N × M × L × S integration problem: every agent, every detector vendor, every LLM protocol, every sandbox wired pairwise. OGR collapses it to N + M + L + S — integrate once against the contract.

Three layers: API → SDK → Plugin

Everything in this repo sits in one of three layers, each built on the one below it:

Layer	What it is	Where
API	The wire contract a runtime (PDP) exposes: `POST /v1/evaluate`, `POST /v1/ingest`, enrollment, heartbeat, config, approvals — carrying `GuardEvent`s and returning `Verdict`s.	Runtime API binding + JSON Schemas
SDK	Language bindings that wrap the API — serialization, auth, request signing, batching — plus the in-process runtime for local evaluation.	`packages/python` (`openguardrails`), `packages/javascript` (`@openguardrails/core`)
Plugin	A hook for one surface — agent, gateway, sandbox, eBPF — that observes actions, builds events, and enforces verdicts, using an SDK for everything below.	`integrations/`

A plugin never speaks HTTP or hand-rolls wire mapping itself; that is the SDK's job. An SDK never invents endpoints; the API is the single normative surface.

The normative components

Component	What it defines	OTel analogue
GuardEvent	The typed unit observed at an interception point	span / log record
Verdict	A detector's decision about an event	—
Provenance	Trust/taint labels on every piece of context	—
guard-context	Correlation of one logical action across gateway / hook / sandbox	trace context (W3C `traceparent`)
composition	How multiple vendors' verdicts combine into one decision	—
enrollment & receipts	How PEPs authenticate to a runtime, and how approvals become verifiable payload-bound artifacts	—
attestation	How strongly identity claims are verified — one ladder for subject assertions and channel auth, with gateway multiplexing guidance	—
Runtime API	The HTTP binding a runtime exposes: `/v1/evaluate`, `/v1/ingest`, enrollment, heartbeat, config, approvals	OTLP/HTTP

Risk categories live in the taxonomy (safety.* and security.*), versioned and swappable — the contract references category IDs but stays neutral on what is "unsafe."

Two domains, one contract

Safety — harmful content/behavior (toxicity, self-harm, CSAM, brand, topic). Mostly classifier-judged at the content I/O boundary.
Security — system compromise (prompt injection, data exfiltration, malicious commands, SSRF, secret leakage, sandbox escape, supply chain). Mostly policy + provenance, enforceable down to the sandbox kernel.

The contract is unified; the pipelines and enforcement points differ. Start with the overview.

Conformance & benchmark

A detector is OGR-conformant if it accepts a GuardEvent and returns a valid Verdict against the JSON Schemas. See CONFORMANCE.md.
The benchmark evaluates conformant detectors on shared corpora and publishes the leaderboard.

Monorepo layout

Path	What it contains
`specification/` and `schema/`	Normative protocol, schemas (JSON Schemas + OpenAPI), taxonomy, conformance, and governance.
`packages/python/`	`openguardrails` — the Python SDK: in-process runtime + `RuntimeClient` for the Runtime API (PyPI).
`packages/javascript/`	`@openguardrails/core` — the JavaScript/TypeScript SDK: in-process runtime + `RuntimeClient` (npm).
`integrations/`	Agent, gateway, sandbox, and eBPF integration categories.
`benchmarks/`	Neutral detector benchmark and leaderboard.
`examples/`	Runnable examples and integration index.
`skills/openguardrails/`	Agent skill for drafting and enforcing policies.
—	openguardrails.com lives in a separate repository; this repo holds the protocol, SDKs, and plugins it documents.

Packages remain independently versioned and published. The monorepo only centralizes source, issues, pull requests, CI, and cross-component changes. See MONOREPO.md for the former-repository mapping and rollout checklist, and RELEASING.md for npm/PyPI release tags.

SDKs and plugins

The Python and JavaScript packages implement the same OGR contract — each is the SDK for its language, and every plugin depends on it:

Python plugins depend on openguardrails.
JavaScript/TypeScript plugins depend on @openguardrails/core.
End users normally install only the plugin; pip or npm installs its SDK dependency automatically. Self-contained marketplace plugins may bundle the SDK so they can run without a separate install step.

Integration categories

Category	Target	Source
Agent hook	Claude Code	`integrations/agent/claude-code`
	Codex	`integrations/agent/codex`
	opencode	`integrations/agent/opencode`
	OpenClaw	`integrations/agent/openclaw`
	DeepSeek Harness (`dsh`)	`integrations/agent/dsh`
	Hermes	`integrations/agent/hermes`
	LangGraph	`integrations/agent/langgraph`
Gateway hook	OpenAI · Anthropic	`integrations/gateway/openai-anthropic`
	Higress (Go/WASM)	`integrations/gateway/higress`
	mitmproxy	`integrations/gateway/mitmproxy`
Sandbox hook	Anthropic srt · NVIDIA OpenShell	`integrations/sandbox` — standalone examples planned
eBPF	OGR reference sensor (kernel process · filesystem · network events)	`integrations/ebpf/sensor`

Development

The JavaScript packages use npm workspaces:

npm install
npm run build
npm test

The Python packages form a uv workspace and can also be installed with pip:

python -m venv .venv
. .venv/bin/activate
python -m pip install pytest
python -m pip install -e packages/python -e integrations/gateway/openai-anthropic \
  -e integrations/agent/hermes -e integrations/agent/langgraph \
  -e integrations/ebpf/sensor
python -m pytest

Principles

Neutral. The protocol is open and foundation-governed; the benchmark is a referee, not a contestant.
Standardize the boundary, not the brains. Detection stays competitive.
Provenance-first. The dangerous thing is usually untrusted input causing a privileged action — so trust labels are a core field, not an add-on.
Defense in depth. Gateway, agent hook, and sandbox observe one action, correlated by guard_id.

Status

Current protocol version: v0.5 (see CHANGELOG.md for protocol versions). Minor versions before v1 may still break between releases; each break is logged. See GOVERNANCE.md for how the spec evolves. Contributions welcome — CONTRIBUTING.md.

License

Apache-2.0.

openguardrails

Installazione

README