Policy Reference

Policies are YAML documents that control what AI agents are allowed, denied, or rate-limited to do. The gateway evaluates every policy before each agent action.

Document Formats

The gateway accepts two formats.

Envelope format (recommended)

Uses apiVersion / kind / metadata / spec wrapping — version-controlled and GitOps-friendly:

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: my-policy         # shown in console and audit log
  version: "1.0.0"        # your policy revision
  description: ...        # optional
spec:
  scope: team:platform
  network:
    allowlist:
      - api.openai.com
  budget:
    daily_limit_usd: 25.0

Flat format

Minimal format without the envelope wrapper — useful for quick testing:

version: "1.0"
scope: global
network:
  allowlist:
    - api.openai.com

Top-Level Fields

Scope

The scope field determines which agents a policy applies to. Policies cascade from broadest to narrowest — Global → Org → Team → Agent → Tool — with most-restrictive-wins merging.

tool:<name> sits at the most-restrictive end of the cascade. A tool-scoped policy can deny slack-mcp for every agent in team:platform even when team- and agent-level policies would otherwise allow it.

Validation: The agent: variant requires a valid hyphenated UUID. The identifier after : must not be empty. Unknown scope kinds (e.g., project:foo) are rejected with a validation error.

network

Controls outbound network connections the agent may initiate.

When network is present but allowlist is absent or empty, no outbound connections are permitted.

network:
  allowlist:
    - "api.openai.com"
    - "*.slack.com"
    - "internal-api.corp.example"

schedule

Restricts the time window during which the agent is permitted to run.

schedule.active_hours

All three sub-fields are required when active_hours is present. start must be earlier than end.

schedule:
  active_hours:
    start: "09:00"
    end: "18:00"
    timezone: "America/New_York"

budget

Caps per-agent LLM spend. The gateway enforces the budget before allowing the agent action.

budget:
  daily_limit_usd: 25.0
  monthly_limit_usd: 500.0
  timezone: "America/Los_Angeles"
  action_on_exceed: deny

data

Scans agent inputs and outputs for PII or credential patterns using regex.

data:
  sensitive_patterns:
    - "sk-[a-zA-Z0-9]{48}"               # OpenAI API key
    - "\\b\\d{3}-\\d{2}-\\d{4}\\b"       # US SSN
    - "(?i)password\\s*[:=]\\s*\\S+"     # password assignment

tools

Per-tool configuration keyed by tool name. Each key in the tools map is a tool name string; the value is a tool policy object.

tools:
  bash:
    allow: true
    limit_per_hour: 10
    requires_approval_if: "governance_level >= L2"
  execute_shell:
    allow: false
  file_write:
    allow: true
    limit_per_hour: 5

requires_approval_if CEL expressions: The expression is evaluated against the tool call context. The identifier governance_level exposes the current agent's governance tier (L0–L3). Referencing an unknown level (e.g., L4) is a validation error.

capabilities

Broad capability allow/deny lists that apply across all tools and actions.

Valid capability strings

Unknown capability strings are rejected with a validation error. The mcp_tool: and model: prefixes require a non-empty name after the colon.

capabilities:
  allow:
    - file_read
    - network_outbound
    - mcp_tool:git
    - mcp_tool:bash
  deny:
    - terminal_exec
    - file_write

approval

Per-policy escalation overrides. When absent, team-level routing defaults are used.

approval:
  timeout_seconds: 600
  escalation_role: org-admin

The top-level approval_timeout_secs sets the default for the whole policy document; approval.timeout_seconds overrides it at the per-policy escalation level.

Validation Rules

The gateway validates every policy on upload. All errors are collected and returned together; the upload is rejected if any error is present.

Unknown keys at any level produce a warning (not an error) — the policy is accepted and the unknown key is ignored. This allows forward-compatible policy files.

Examples

Minimal — budget cap only

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: budget-only
  version: "1.0.0"
spec:
  budget:
    daily_limit_usd: 10.0
    action_on_exceed: deny

Network egress allowlist

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: allowlist-openai-slack
  version: "1.0.0"
spec:
  scope: team:platform
  network:
    allowlist:
      - "api.openai.com"
      - "*.slack.com"

Capability control

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: capability-example
  version: "1.0.0"
spec:
  scope: global
  capabilities:
    allow:
      - file_read
      - network_outbound
      - mcp_tool:git
      - mcp_tool:bash
    deny:
      - terminal_exec
      - file_write

Tool rate-limiting with approval gate

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: guarded-tools
  version: "1.0.0"
spec:
  tools:
    bash:
      allow: true
      limit_per_hour: 10
      requires_approval_if: "governance_level >= L2"
    execute_shell:
      allow: false

Business-hours schedule

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: business-hours-only
  version: "1.0.0"
spec:
  scope: team:ops
  schedule:
    active_hours:
      start: "09:00"
      end: "18:00"
      timezone: "America/New_York"

PII detection

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: no-pii-in-output
  version: "1.0.0"
spec:
  data:
    sensitive_patterns:
      - "sk-[a-zA-Z0-9]{48}"
      - "\\b\\d{3}-\\d{2}-\\d{4}\\b"

Full policy — all sections

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: production-full
  version: "1.0.0"
  description: Full example combining all policy sections.
spec:
  scope: team:platform
  network:
    allowlist:
      - "api.openai.com"
      - "slack.com"
  schedule:
    active_hours:
      start: "09:00"
      end: "18:00"
      timezone: "Asia/Taipei"
  budget:
    daily_limit_usd: 25.0
    monthly_limit_usd: 500.0
    action_on_exceed: deny
  data:
    sensitive_patterns:
      - "sk-[a-zA-Z0-9]{48}"
  tools:
    bash:
      allow: true
      limit_per_hour: 10
    file_write:
      allow: false
  capabilities:
    allow:
      - file_read
      - network_outbound
    deny:
      - terminal_exec
  approval_timeout_secs: 300
  approval:
    escalation_role: org-admin

Related Documentation

• Security Model — IronClaw layers and policy engine position in the stack
• Cloud Deployment — uploading and activating policies in the console
• Quick Start (SaaS) — create and activate your first policy

Last reviewed: 2026-05-10 · AI Agent Assembly Team