Policies Overview

Policies define what your agents can do. Each policy is a list of rules. When an action is submitted, Faramesh checks the rules in order; the first match determines whether the action is allowed, denied, or needs your approval.

Basic structure

Each rule has:

Match - When does this rule apply? (by tool, operation, etc.)
Effect - What happens? Allow, deny, or require approval

Example:

rules:
  - match:
      tool: shell
      operation: exec
    require_approval: true
    reason: "Shell commands need approval"

  - match:
      tool: database
      operation: drop_table
    deny: true
    reason: "Dropping tables is not allowed"

  - match:
      tool: http
      operation: get
    allow: true
    reason: "Read-only requests are safe"

rules:
  - match:
      tool: shell
      operation: exec
    require_approval: true
    reason: "Shell commands need approval"

  - match:
      tool: database
      operation: drop_table
    deny: true
    reason: "Dropping tables is not allowed"

  - match:
      tool: http
      operation: get
    allow: true
    reason: "Read-only requests are safe"

rules:
  - match:
      tool: shell
      operation: exec
    require_approval: true
    reason: "Shell commands need approval"

  - match:
      tool: database
      operation: drop_table
    deny: true
    reason: "Dropping tables is not allowed"

  - match:
      tool: http
      operation: get
    allow: true
    reason: "Read-only requests are safe"

Match conditions

You can match on:

tool - shell, github, stripe, http, etc.
operation - exec, refund, merge_pr, etc.
params - Nested conditions (e.g. block commands containing "rm -rf")

Use * for wildcards: tool: "*" matches any tool, operation: "delete_*" matches delete_table, delete_row, etc.

Effects

allow - The action runs immediately
deny - The action is blocked
require_approval - The action pauses until you approve or deny

Each rule has exactly one effect.

Default behavior

If no rule matches, the action is denied. Add a catch-all at the end if you want unmatched actions to be allowed:

  - match:
      tool: "*"
      operation: "*"
    allow: true
    reason: "Default: allow with monitoring"

  - match:
      tool: "*"
      operation: "*"
    allow: true
    reason: "Default: allow with monitoring"

  - match:
      tool: "*"
      operation: "*"
    allow: true
    reason: "Default: allow with monitoring"

Managing policies

Policies are database-backed and versioned. On first startup, existing YAML files under /policies/*.yaml are imported once; the engine then reads only from the database.

Horizon: Use the dashboard Policies page: simple Governance tab (Allow/Ask/Deny per category) and Advanced tab (full JSON/YAML editor with live toggle). Create, edit, and activate policies without redeploying.
Self-hosted: Use the same dashboard, or the API and CLI. No dual YAML+DB system—all changes go through the store.

See Database-backed policies and editor for migration, API (POST /v1/policies/import-yaml), security limits, and CLI. See Policy recipes for ready-to-use examples.

Table of content