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:

1. Match — When does this rule apply? (by tool, operation, etc.)

2. 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.