nodrail

Agent Policy Format (APF)

Agent Policy Format is an open YAML format for defining which tool calls an AI agent may make. Keep a policy in your repository, review changes in a pull request and test expected decisions with Nodrail’s open-source engine.

A policy can travel between harnesses when their adapters describe the same operations and resources and supply the facts its rules require. Each harness enforces the returned decision. The local Claude Code hook reads policy files directly. In a custom tool runner, place the evaluator before invocation. The documented Codex plugin uses workspace policies through Nodrail Cloud.

Try APF locally · Integrate your own harness · Compare integrations

Start with a small policy

This example uses fictional repositories and operations. Adapt the names and action mapping to your integration; it does not connect to GitHub or execute anything.

- required_engine_version: 2

- rule: Read issues
  tool: github
  operation: issues.read
  resource: { kind: repository, match: any }
  effect: allow

- rule: Review production updates
  tool: github
  operation: issues.update
  resource: { kind: repository, match: exact, value: acme/production }
  effect: require_approval

- rule: Never delete repositories
  tool: github
  operation: repositories.delete
  resource: { kind: repository, match: any }
  effect: deny

Save it as rules.yaml. Use the CLI installed from @nodrail/policy-engine, or nodrail policy from @nodrail/cli, which takes the same commands:

pnpm add --global @nodrail/policy-engine
nodrail-policy validate rules.yaml
nodrail-policy eval rules.yaml --tool github --operation issues.read --kind repository --resource acme/demo

validate checks the file, not your integration's security. eval prints the decision and exits successfully even when that decision is deny. Do not use eval's exit code as an execution gate.

For a command gate, use check or exec: both block everything except allow. exec really launches the supplied program if allowed; evaluation and validation do not. Read the CLI reference (nodrail-policy) before using it.

Understand the four outcomes

OutcomeMeaningIntegration responsibility
allowThe declared action matches applicable allow policy and no stronger matching rule wins.Enforce the result for that action; this is not evidence that it ran.
denyA matching deny rule takes precedence.Do not invoke the tool.
require_approvalHuman review is required by a matching rule.Stop and hand off to the runtime's supported review mechanism. It is not approval itself.
noneNo rule matches.Do not interpret it as allow. Block, or explicitly route to an authorized review flow.

Every matching rule participates. Deny takes precedence over review, which takes precedence over allow. Rule order does not create first-match-wins behavior. File order matters for explicitly overriding definitions, not for changing effect precedence.

A standing allow rule is a reusable authorization rule. It is different from approving one exact action. Adding effect: allow does not create shared human-approval state, a one-time permit or an authenticated delegation.

Learn the file structure

Level 3 preview. Gates and budgets use run history supplied by the integration and need engine 0.2.0 or later. The local quickstart uses level-2 rules and works with any public release.

The root is a YAML list. Each item is one of:

  • required_engine_version: minimum engine feature level.
  • rule: a named policy rule.
  • list: reusable scalar values.
  • macro: reusable conditions.
  • gate and budget: rules about what already happened in a run, from engine level 3. See Runs, gates and budgets (preview).

An active tool rule needs tool, operation, resource and effect. A command rule uses command plus effect instead of the tool/operation/resource trio. A rule cannot combine both forms. Names are unique within their entry type; changing an existing definition requires an explicit override.

Optional rule fields include id, title, desc, tags, condition, agent, installation, expires and enabled. Keep explicit IDs stable when renaming rules. Identity selectors match caller-declared attributes; the standalone engine does not authenticate those values.

Resources support any, literal exact and literal prefix matching, or expansion from a named list. A resource prefix is text, not a filesystem boundary or regular expression: acme/app also matches acme/application. Command prefixes have their own normalization and word-boundary semantics; do not transfer resource-prefix assumptions to them.

Conditions use structured entries, not executable expressions. Operators are eq, neq, gt, gte, lt, lte, in and contains. Conditions in one rule are combined with AND. There is no general OR expression; use separate rules or the documented list expansion. Missing or incorrectly typed parameters never help an allow rule; deny/review matching is conservative when facts cannot be evaluated.

For guard() and MCP descriptors, tool arguments are under input, so a field may be input.amount. For a hand-written eval --params call, it is the field you actually provide, such as amount. Consult Commands and tools and the SDK descriptor contract before copying conditions between integrations.

Layer policies deliberately

The CLI loads explicit files in argument order. A directory loads its immediate .yaml and .yml files in filename order. It does not promise recursive discovery or automatic loading of a special filename. To combine ready-made modules with your own files in a fixed, reviewed order, use a project's nodrail.yaml: see Playbooks (preview).

Redefining a name without override is an error. Use replace to change a scalar field, and the supported append forms for lists, conditions and tags. An override must name every field it changes. This is deliberate: a later file should not silently weaken an earlier rule.

The compiler refuses invalid definitions, unresolved references, duplicate YAML keys and a declared engine level newer than it supports. Current limits include 1 MiB per file, 500 compiled rules and 20 expanded conditions per rule. List and command expansion count toward the compiled-rule limit. YAML aliases have a limit; use named lists/macros instead of relying on alias expansion.

See the maintained Rules reference for exact forms and limits. These overview examples do not replace it.

How do I test an agent’s permissions before giving it GitHub access?

Create cases.yaml:

- name: reads are allowed
  call: { tool: github, operation: issues.read, kind: repository, resource: acme/demo }
  expect: allow

- name: production updates need review
  call: { tool: github, operation: issues.update, kind: repository, resource: acme/production }
  expect: require_approval

- name: deletion is denied
  call: { tool: github, operation: repositories.delete, kind: repository, resource: acme/demo }
  expect: deny

- name: an unrecognized operation has no rule
  call: { tool: github, operation: issues.close, kind: repository, resource: acme/demo }
  expect: none

Run:

nodrail-policy test rules.yaml --cases cases.yaml
nodrail-policy compile rules.yaml

test exits with 1 if a case fails. compile outputs JSON for the engine; it does not authorize or execute a tool. Add denial, unknown-operation, identity, expiry, missing-field and type-mismatch cases relevant to your integration. Validation success is not a substitute for checking whether the tool was invoked after a denial or a timeout.

Know the boundary

A hook or SDK can stop calls that pass through its enforced checkpoint. A runtime that ignores the result, an agent that can remove the hook, direct credentials, an alternative network route, or an allowed script containing other operations can bypass that boundary. Complete containment requires independent controls over runtime permissions, configuration, credentials and network routes.

The local engine does not host your agents, issue cloud approval permits or prove an action completed. For full limits and integration-specific behavior, read the Security model, Try APF locally and Integrate your own harness.

Where do I declare gates and budgets?

Add gate: and budget: as top-level entries alongside rule: in the same APF YAML file. Gates and budgets require required_engine_version: 3 and a runner that supplies the history they use. A rule grants or restricts an operation. A gate adds a prerequisite, such as QA reporting a pass. A budget sets a limit, such as 60 tool calls per builder step. Satisfying a gate or staying within a budget still requires a rule that permits the operation. Runs, gates and budgets (preview)

In Cloud, choose the workspace and environment, then open Policies → YAML to edit the file. Select Review changes, then Publish rules. Policies → Gates and Policies → Budgets list the active ones, and you can also add, edit and remove them there. Cloud policy views

In our GitHub merge check pilot, an adapter also checked which commit the receipt covered. GitHub required the adapter’s status on the target branch. Read the GitHub merge check pilot.

Versions

Keep three concepts separate: the npm package release, the YAML file's required_engine_version and the compiled JSON document's version. Rules, lists and macros need feature level 2 and compile to JSON version: 1. Gates and budgets need feature level 3 and compile to JSON version: 2, which engines before level 3 reject rather than ignore. There is no accepted apiVersion or format header in the YAML authoring file. Pin the engine release in projects and test policies when upgrading.