Guardrails

Before an AI worker touches your codebase — and again after it finishes — guardrails run automated safety checks to catch problems early. They act as gatekeepers: a guardrail can warn you about a potential issue or block a dispatch entirely.

What guardrails are

A guardrail is a defined check that runs at a specific point in the agent run lifecycle. Each guardrail examines some aspect of the dispatch (the prompt, the workspace, the diff, or the output) and produces a pass/fail result with an optional message explaining what it found.

Each guardrail definition includes:

Field	Purpose
Guardrail code	A unique identifier (e.g. SECRET_SCAN)
Name	A human-readable display name
Guardrail type	When the check runs — before or after dispatch (see below)
Check type	How the check is performed — deterministic rules or AI evaluation
Severity	What happens on failure — warn or block (see below)
Role scope	Which role this guardrail applies to — or all roles if unset
Configuration	Check-specific settings (thresholds, patterns, limits)

Guardrails are tenant-scoped and can be customised per tenant. Raytio ships with a set of built-in guardrails that cover common safety concerns.

Guardrail types

Guardrails run at one of two points in the dispatch lifecycle:

Pre-dispatch

PRE_DISPATCH guardrails run before the agent is dispatched. They examine the prompt and workspace to catch problems before any AI execution begins — and before any cost is incurred.

Use cases:

• Scanning the prompt for leaked secrets or credentials
• Verifying that the cost budget has not been exhausted

If a blocking pre-dispatch guardrail fails, the dispatch is aborted and the agent run is marked FAILED immediately. No tokens are consumed.

Post-dispatch

POST_DISPATCH guardrails run after the agent completes its work but before the merge request is created. They examine the agent's output, the diff, and any changed files.

Use cases:

• Scanning committed files for credential leaks
• Checking that the diff is not unreasonably large
• Verifying that the agent did not modify forbidden paths
• Validating that the agent's output matches the expected schema
• Evaluating whether the agent's changes stayed within scope

If a blocking post-dispatch guardrail fails, the run is marked FAILED and merge request creation is skipped.

Check types

Each guardrail uses one of two execution methods:

Rule-based

RULE_BASED guardrails use deterministic logic — pattern matching, threshold checks, file inspection. They are fast, cheap, and produce consistent results. Each rule-based guardrail specifies a check function that examines its inputs and returns pass or fail.

Rule-based checks run inline during the dispatch process and produce results immediately.

Model-graded

MODEL_GRADED guardrails use an AI model to evaluate the agent's work. They specify an eval prompt that is filled with context from the run (diff, output, work item description) and sent to an evaluation model. This makes them well-suited to subjective assessments that cannot be captured with pattern matching alone.

Model-graded checks run asynchronously — they create an eval work item that is dispatched separately, following the same pattern as eval scorers. This means model-graded guardrails do not block merge request creation.

tip

Model-graded guardrails are only supported for POST_DISPATCH checks. Pre-dispatch checks must be rule-based to avoid delaying the dispatch with an expensive AI call.

Severity levels

When a guardrail check fails, the severity determines what happens next:

Severity	Behaviour
WARN	The result is recorded but execution continues normally
BLOCK	Execution is halted — the dispatch is aborted or the run is failed

A WARN severity is appropriate for checks that flag potential issues without certainty — for example, a diff that exceeds a recommended size threshold but might be legitimate. A BLOCK severity is appropriate for checks where failure represents a clear policy violation — for example, leaked credentials in the diff.

Built-in guardrails

Raytio ships with seven built-in guardrails that cover common safety and quality concerns:

SECRET_SCAN

Type	PRE_DISPATCH
Check	RULE_BASED
Severity	BLOCK

Scans the prompt for API key patterns, passwords, and connection strings before sending it to the agent. Catches accidental credential exposure in work item descriptions or prompt context.

BUDGET_GATE

Type	PRE_DISPATCH
Check	RULE_BASED
Severity	BLOCK

Verifies that the cost budget has not been exhausted before dispatching the agent. This reuses the budget check described in Cost Management — if the current period's spend has reached the budget limit, the dispatch is blocked.

CREDENTIAL_LEAK

Type	POST_DISPATCH
Check	RULE_BASED
Severity	BLOCK

Scans the agent's committed files for secrets — API keys, tokens, passwords, and private keys. Unlike SECRET_SCAN (which checks the prompt), this guardrail checks what the agent actually wrote into the codebase.

DIFF_SIZE_LIMIT

Type	POST_DISPATCH
Check	RULE_BASED
Severity	WARN

Flags diffs that exceed a configurable size threshold. Large diffs are harder to review and more likely to contain unintended changes. The default threshold is 500 lines (insertions + deletions), configurable through the guardrail's config field.

tip

DIFF_SIZE_LIMIT uses WARN severity by default — it flags large diffs for attention but does not block them. Some tasks legitimately produce large diffs (e.g. code generation, bulk refactoring). If you want to enforce a hard limit, change the severity to BLOCK.

FORBIDDEN_PATHS

Type	POST_DISPATCH
Check	RULE_BASED
Severity	BLOCK

Checks that the agent did not modify files in protected paths. By default, this includes CI/CD configuration files, deployment scripts, and infrastructure definitions:

• .gitlab-ci.yml
• serverless.yml
• deploy.sh
• Dockerfile

The list of forbidden patterns is configurable through the guardrail's config field. If the work item description explicitly permits changes to a forbidden path, the check is overridden.

OUTPUT_SCHEMA

Type	POST_DISPATCH
Check	RULE_BASED
Severity	BLOCK

Validates the agent's structured JSON output against a schema defined in the worker definition. This ensures that the agent produces output in the expected format — status, branch name, summary, file list, and any role-specific fields.

On failure, the system retries once with schema feedback appended to the prompt. If the second attempt also fails, the run is marked INVALID_OUTPUT.

SCOPE_VALIDATION

Type	POST_DISPATCH
Check	MODEL_GRADED
Severity	WARN

Uses an AI evaluator to assess whether the agent's changes stayed within the scope of the work item description. This catches scope creep — agents that refactor unrelated code, add unrequested features, or make changes beyond what was asked for.

Because this is a model-graded check, it runs asynchronously and does not block merge request creation.

Custom guardrails

You can define custom guardrails to enforce policies specific to your organisation. A custom guardrail follows the same structure as a built-in one — you specify the guardrail type, check type, severity, and either a check function (for rule-based) or an eval prompt (for model-graded).

Custom guardrails can be scoped to a specific role. For example, you might create a guardrail that only applies to the DB_MIGRATION role to check that migration files follow a naming convention, while leaving other roles unaffected.

Reviewing guardrail results

Every guardrail check produces a result record linked to the agent run:

Field	What it contains
Passed	Whether the check passed or failed
Message	Failure reason or warning details
Metadata	Raw check output — matched patterns, validation errors, etc.

Results are stored per guardrail per run. You can review them to understand why a run was blocked, what warnings were raised, or whether a particular guardrail is producing too many false positives.

Over time, guardrail results build up a dataset that helps you tune your safety configuration — for example, adjusting the diff size threshold based on your team's actual merge patterns, or identifying agents that frequently trigger credential leak warnings.

How guardrails connect to other modules

• Agent runs — guardrail results are linked to the agent run they checked. The GUARDRAIL run step tracks guardrail execution within the run timeline. See Agent Runs for details.
• Eval scorers — model-graded guardrails use the same async evaluation pattern as eval scorers. See Eval Scorers for details.
• Cost management — the BUDGET_GATE guardrail integrates directly with the budget system. See Cost Management for details.