Policy-as-Code

Define and manage your AI agent governance policies declaratively using YAML files. Version-control your policies alongside your code.

---

Overview

Policy-as-code lets you:

• Define policies in YAML — MCP servers, approval workflows, tool configurations, and defaults
• Version and diff — Track changes, compare against live config, rollback to previous versions
• Validate before applying — Catch errors without affecting your running system
• Import/export — Move policies between environments (dev → staging → production)

---

Policy Schema

Every policy document follows this structure:

version: "1.0"
metadata:
  name: my-policy
  description: Policy for production safety
  author: team@company.com
  tags: [production, safety]

mcp_servers:
  - name: github
    url: https://api.github.com/mcp
    transport: http-streaming
    auth_type: bearer
    auth_config:
      token: ${GITHUB_TOKEN}

approval_workflows:
  - name: sre-review
    timeout_seconds: 600
    required_approvals: 1
    approvers:
      - team: sre-team

tools:
  - name: bash
    source: builtin
    enabled: true
    approval_workflow: sre-review
    conditions:
      - expression: "args.command.contains('rm')"
        action: deny
        description: Block destructive commands

defaults:
  unknown_tools: require_approval
  require_approval_for_new_tools: true
  default_approval_workflow: sre-review

---

Schema Reference

version (required)

Schema version. Currently only "1.0" is supported.

metadata (required)

Field	Type	Required	Description
name	string	✅	Unique policy name
description	string		Policy description
author	string		Author name or email
tags	list		Tags for categorization

mcp_servers

Define external MCP servers that tools can reference.

Field	Type	Default	Description
name	string	—	Unique server name (referenced by tools)
url	string	—	Server endpoint URL
transport	string	http-streaming	http-streaming, streamable-http, stdio, sse
auth_type	string	none	none, bearer, api_key
auth_config	object	—	Auth details. Use ${ENV_VAR} for secrets

approval_workflows

Define how approvals are handled. See AI-Driven Approvals for AI-specific options.

Field	Type	Default	Description
name	string	—	Unique policy name
timeout_seconds	int	3600	Timeout before auto-action
required_approvals	int	1	Number of approvals needed
approvers	list	—	List of approver configs
approval_type	string	standard	standard or ai_driven

tools

Configure individual tool behaviors.

Field	Type	Default	Description
name	string	—	Tool name (must match actual tool)
source	string	builtin	builtin, mcp, http, or a server name
enabled	bool	true	Whether the tool is active
approval_workflow	string	—	Name of approval workflow to use
conditions	list	—	List of conditional rules
description	string	—	Override tool description

Tool Conditions

Each condition evaluates against tool arguments:

Field	Type	Default	Description
expression	string	—	Expression to evaluate
action	string	require_approval	allow, deny, or require_approval
condition_type	string	simple	simple (OSS) or cel (Enterprise)
description	string	—	Human-readable description

defaults

Field	Type	Default	Description
unknown_tools	string	allow	allow, deny, or require_approval
require_approval_for_new_tools	bool	true	Require approval for new tools
default_approval_workflow	string	—	Fallback approval workflow
inherit_from_parent	bool	true	Inherit from parent policy

---

CLI Commands

# Validate a policy file (no changes applied)
preloop policy validate my-policy.yaml

# Preview what would change
preloop policy diff my-policy.yaml

# Apply a policy
preloop policy apply my-policy.yaml

# Dry-run (preview without applying)
preloop policy apply my-policy.yaml --dry-run

# Export current config as YAML
preloop policy export my-policy

# List all policies
preloop policy list

---

API Endpoints

Method	Endpoint	Description
POST	/api/v1/policies/validate	Validate policy syntax
POST	/api/v1/policies/diff	Compare against current state
POST	/api/v1/policies/import	Import and apply a policy
GET	/api/v1/policies/export	Export current config as YAML

---

Versioning & Rollback

Preloop maintains a history of policy changes, allowing you to rollback to any previous version.

# List policy versions
GET /api/v1/policies/versions

# Create a snapshot
POST /api/v1/policies/versions

# Tag a version
PUT /api/v1/policies/versions/{id}/tag
# Body: { "tag": "production-v1" }

# Rollback to a version (with diff preview)
POST /api/v1/policies/versions/{id}/rollback

# Delete old versions
DELETE /api/v1/policies/versions/{id}

Credential Safety

Rollbacks preserve MCP server credentials — only configuration changes are reverted.

---

Validation Rules

The schema validates:

1. No duplicate names — MCP server and approval workflow names must be unique
2. Valid references — Tools referencing approval workflows or MCP servers must point to defined names
3. AI policy completeness — AI-driven policies require ai_model and ai_guidelines
4. Expression syntax — Tool condition expressions cannot be empty
5. Default references — default_approval_workflow must reference a defined policy

If validation fails, you get detailed error messages pointing to the exact issue:

{
  "is_valid": false,
  "errors": [
    {
      "path": "tools[0].approval_workflow",
      "message": "Tool 'bash' references unknown approval workflow 'nonexistent'"
    }
  ]
}