OpenGuardrail

English | 简体中文

Evidence-based action guardrails for AI agents.

OpenGuardrail is a standalone guardrail service for AI agents that operate real systems.

Developers define the checks required before an action. The agent follows the policy, performs the checks and submits results and evidence. OpenGuardrail validates the submission, records the assessment and returns ALLOW or DENY. The execution tool verifies the decision and its validity before acting.

Each assessment links the policy revision, check results, evidence and decision for verification and audit. Agents and tools use the HTTP API or the guardrailctl CLI.

Status: development preview. The API is v1alpha1. See current capabilities and limits for details.

The agent proposes; the gate decides. OpenGuardrail validates the structure and completeness of evidence; the calling system verifies observations and applies the decision.

Source · Issues · Get started · Documentation · API and CLI · Deployment · Contributing · Apache-2.0

See it in action

A predefined Python runner asks to delete four files: two temporary files, plus orders.csv and config.yaml. The broad request is blocked because it includes protected files and exceeds the batch limit. The runner narrows the request; the second Run passes and the execution tool deletes only the two temporary files.

Predefined runner, real service and files; this demo does not use an AI model. Start it with python3 examples/cleanup-demo/demo.py.

Why OpenGuardrail?

When an agent has permission to operate real systems, required checks need to be enforced at execution time. Prompts can tell the agent to check first, but execution tools still need a verifiable basis for allowing an action. Audits also need a clear record of the policy, check results and evidence used at the time.

If that information lives only in agent conversations and tool logs, each execution tool must extract and correlate it before deciding whether to proceed. OpenGuardrail organizes it into a consistent assessment record for tools to verify before acting and for later audits.

Where it fits

Use it when: An agent or automation may delete data, deploy an application, or change configuration, and the team needs a traceable record of the policy, checks and evidence behind each decision.

Integration requirement: An agent or integration performs the checks and submits results and evidence. The tool that actually performs the operation reads the authoritative Run before acting and verifies the decision's validity, the evidence it relies on and, where relevant, the current target state.

Limits: OpenGuardrail validates the submission against the policy and records ALLOW or DENY; it does not independently verify the observations. A recorded ALLOW does not grant permission for the business operation. Actions that bypass the integrated tool are outside this check, and OpenGuardrail does not isolate processes or networks.

The scenario packages show where concrete checks, evidence collection and execution gates live. The agent plugin provides one pi entrypoint and loads the bundled scenarios.

How it works

A Scene groups policies for one type of operation. Scenes share the same policy, evidence and decision model. An assessment moves through five steps:

1. Publish a policy. Define checks and evidence requirements in a GuardrailSpec and publish an immutable revision, then activate it for the Scene.
2. Start an assessment. Create a Run to record the operation's context and freeze the selected policy revision and evaluation deadline.
3. Check and submit. The agent reads the Run's policy requirements, performs the checks with its tools, and submits complete results and evidence. Intermediate snapshots can precede a final submission.
4. Read the decision. Query the authoritative Run for its stored decision and validity, then read its referenced Submission to inspect the evidence.
5. Verify before acting. The execution tool checks the authoritative decision, its validity and the evidence, then applies business rules before acting.

For a completed Run, the check results aggregate as follows:

Result	Meaning	Decision
PASS	All checks pass	ALLOW
BLOCKED	At least one check reports a confirmed failure	DENY
UNKNOWN	No check is blocked, but at least one cannot be assessed	DENY

An unfinished Run can expire, and a completed decision has its own validity window. Integrations must check the authoritative Run, its deadline and decision validity. See Runs and submissions.

Quickstart

Run the same workflow locally and watch a guarded tool act on real files in a disposable directory. This trial needs no model account, Jenkins, Docker or separate database.

Run a guarded task

Published native previews appear in GitHub Releases. Choose the native archive for your platform and SHA256SUMS; plugin users also choose the complete -install.tar.gz plugin archive. Follow archive verification before extracting and running the same cleanup demo with Python 3.9+; the native path needs no Go installation. For a model-driven pi/DeepSeek Harness trial, use the separate plugin installation guide. The commands below build from source.

Install Git, the Go version specified in go.mod and Python 3.9+:

git clone https://github.com/alibaba/open-guardrail.git
cd open-guardrail
python3 examples/cleanup-demo/demo.py

Choose a console password at the hidden prompts. The script builds both commands from source, then prints a Demo URL and a Console URL. Open the Demo first; it needs no login.

Click Run cleanup task. The initial request includes temporary files, orders and configuration. A predefined runner submits the observed file state and gets a real DENY. It narrows the request, creates another Run and gets ALLOW. The controlled tool verifies that Run and its evidence before deleting only the temporary files. Orders and configuration remain on disk.

Change the selected files, disable automatic revision or lower the batch limit, then run again. Expand a Run to inspect its frozen policy and accepted evidence. The runner uses no model; the service calls and file operations are real. See the demo guide for the workflow and limits.

Keep the terminal open. Ctrl-C stops both services and removes their temporary data and credentials. The separate Console uses username demo and the password chosen at startup; its Runs page contains the same Run IDs. For the original four-case Recovery contract self-check, run python3 examples/agent-demo/smoke.py.

Start a persistent service

To keep a service running and inspect your own Runs in the browser, use Go and Make from the checkout root:

make build
./bin/open-guardrail serve

Open http://127.0.0.1:8080 and create the first administrator. There is no default password. SQLite stores data in ./data; no separate database service is needed.

Next steps

Goal	Guide
Understand how a policy affects a decision	Getting started: publish a policy, submit an assessment and inspect its evidence
Have an agent perform the checks	Agent demo: let an agent assess the sample observations and submit its findings
Protect an operation in my own tool	Integration guide and API and CLI: define the checks, connect observation sources and verify the decision in your execution tool

Target architecture

The target architecture below uses CD delivery as one example of the shared guardrail model. An agent follows a Scene's checks and submits evidence; OpenGuardrail validates the submission and records a decision; the execution tool verifies the decision and evidence before acting. Blue components belong to OpenGuardrail; gray components represent the agent and external systems.

Open the diagram for the full-size SVG. Execution Claims and receipts, replaceable providers, and some CD integrations remain planned. The server validates evidence structure and completeness; the calling system verifies the observations. See current capabilities and limits and reference integrations for what works today.

Current capabilities and limits

The preview includes:

• A standalone Go service, an HTTP CLI and an embedded management UI.
• Local administrator setup, browser/CLI sessions and scoped machine credentials with bounded lifetimes, metadata listing, secret rotation and revocation.
• Scenes, editable policy drafts and immutable policy revisions.
• Runs with frozen policy/evaluation context, intermediate and final submissions, structured evidence, expiry and stored decisions.
• SQLite and PostgreSQL adapters, with one service instance per database.
• Native packaging for Linux and macOS on amd64 and arm64, plus optional Docker deployment behind HTTPS.

The current boundaries are:

• Checks run outside the service, in your agent or integration. The server does not independently verify submitted observations. Registration and attestation of external evaluators are not implemented.
• Applying a decision and controlling actions belong to the calling system. Execution Claims and ActionResults remain planned.
• Multi-instance operation and replaceable identity/provider APIs are not yet supported.
• Alpha APIs and storage contracts may change during the preview.

See the roadmap, runtime architecture and security policy for details.

Reference integrations

Use the versioned HTTP/OpenAPI contract or the shared CLI to connect an application, service, script or agent. The examples cover local file operations and delivery workflows.

Integration	Current status
Live file cleanup demo	Real Runs and guarded deletion in a disposable directory; predefined runner without a model
Local Recovery Agent demo	Synthetic observations; agent-driven assessment and a deterministic self-check
Jenkins	Synthetic pipeline demo with an outside agent and delivery-side evidence verification
Argo Rollouts	Synthetic Analysis Job demo
GitHub Actions	Planned adopter-facing workflow
Argo CD	Sync hooks planned

These examples demonstrate integration contracts. See the integration guide for their scope and prerequisites.

Documentation

Start with the documentation index for reading paths, or read core concepts for the Scene, Policy, Run and Submission model.

I want to…	Start here
Run a local example and inspect a decision	Getting started
Configure storage or a remote service	Configuration and storage, Docker deployment
Manage administrators and credentials	Administrator guide
Write and publish a GuardrailSpec	GuardrailSpec YAML reference, Scenes and Specs
Create Runs and submit evidence	Runs and submissions
Call the API or automate with the CLI	API overview, CLI guide
Understand the implementation or extension plans	Architecture, extension boundaries
Build, contribute or prepare a release	Development, release notes, release verification

Contributing and support

Bug reports, documentation improvements, integration feedback and focused code changes are welcome. Read CONTRIBUTING.md for setup, issue guidance and the pull request workflow.

Use GitHub Issues for questions and reproducible bug reports. Include your version and a minimal example with synthetic data. Report vulnerabilities privately through SECURITY.md. Community participation follows our Code of Conduct.

License

OpenGuardrail is licensed under the Apache License 2.0. Third-party components retain their original terms; see the notice inventory and dependency review.