nodrail

Try APF locally

Use one YAML file to answer three questions. May an agent inspect the working tree? May it remove untracked files? What happens if it asks to read the commit history? You can try all three on your machine without a Nodrail account.

Install

Use Node.js 22 or later. Install the CLI, then open an empty directory for the example.

npm i -g @nodrail/policy-engine

With pnpm, run pnpm setup once so pnpm has a folder for global commands, then pnpm add --global @nodrail/policy-engine.

This page uses nodrail-policy. If you use nodrail, Nodrail's one command line, write nodrail policy instead: it takes the same commands and flags and gives the same output and exit codes.

Write rules

Save this file as rules.yaml.

- required_engine_version: 2
- rule: Inspect the working tree
  command: git status
  effect: allow
- rule: Protect untracked files
  command: git clean -fd
  effect: deny

Validate the file, then ask the evaluator about three proposed commands. Each command in quotes is input to the evaluator. Your working tree stays untouched.

nodrail-policy validate rules.yaml
nodrail-policy eval rules.yaml --command "git status"
nodrail-policy eval rules.yaml --command "git clean -fd"
nodrail-policy eval rules.yaml --command "git log"

Validation prints OK and a count of 2 rules. Each evaluation prints JSON. Read its outcome field.

Proposed commandExpected outcomeWhy
git statusallowMatches “Inspect the working tree”.
git clean -fddenyMatches “Protect untracked files”.
git lognoneNeither rule covers the proposed command.

Test your rules in CI

Save these expectations as cases.yaml alongside rules.yaml.

- name: Inspecting the working tree is allowed
  call: { command: git status }
  expect: allow
- name: Cleaning untracked files is denied
  call: { command: git clean -fd }
  expect: deny
- name: A command without a matching rule is undecided
  call: { command: git log }
  expect: none

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

An exit code of 0 means all three expectations matched. A failed case exits with 1. Commit both files to review policy changes alongside their expected decisions.

Connect Claude Code

This step is optional. To apply the example policy to covered tool calls, put rules.yaml at the root of a test project. In Claude Code 2.1.295 or later, add this entry to the project's .claude/settings.json. Merge it with any hooks you already use.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "nodrail-policy hook \"$CLAUDE_PROJECT_DIR/rules.yaml\"",
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

The hook lets Claude Code continue on allow, blocks on deny, and asks the person at the keyboard on require_approval. It blocks unmatched calls by default. Set --unmatched ask if you want Claude Code to ask about those calls. Keep onFailure set to block so an error starting the hook stops the covered call. Protect the hook settings and policy from changes by the agent.

Try the hook without Claude Code

From the example directory, send the hook a proposed call as JSON.

printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git log"}}' | nodrail-policy hook rules.yaml

The JSON response contains permissionDecision set to deny. The evaluator found none for the same input. The hook applied its default for an unmatched call.

Choose a starter policy for a project

The two-rule example is deliberately small. To start a project policy, choose a pack and review the generated file before pointing a hook at it. Run the chosen command in a directory where the named output file is new.

Read-only allows inspection. Save it as read-only.yaml.

nodrail-policy init read-only > read-only.yaml

Repo work also allows selected edits, tests and commits. Save it as repo-work.yaml.

nodrail-policy init repo-work > repo-work.yaml

Validate the pack you chose with nodrail-policy validate read-only.yaml or nodrail-policy validate repo-work.yaml. Place the reviewed file at the project root and update the filename in the hook command to match. Keep the example cases paired with the original two-rule policy.

Gate commands in scripts

For a script that needs an exit code, use check. It exits with 0 on allow and 1 when the policy blocks the command.

nodrail-policy check rules.yaml -- git status

Share this policy with your team

This step needs a Nodrail Cloud workspace. Cloud reads the same Agent Policy Format, so the rules.yaml you just tested imports as it is.

  1. Create a free workspace. Cloud Free includes 1,000 governed actions per workspace each month.
  2. Open Policies, choose Import YAML and upload rules.yaml.
  3. Choose Preview to see the rules the file adds, changes or removes, then Publish rules. The file replaces the environment's rules, so start from an empty environment or export the current rules first.
  4. In Agents, choose Connect an agent and follow the steps for the Claude Code plugin. Its covered calls are then decided by the shared rules, and calls the rules leave to a person wait in Approvals for your team.

Export YAML brings the file back, so the copy in your repository and its cases.yaml stay the source you review. See Using Nodrail Cloud.

Where to go from here