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 command | Expected outcome | Why |
|---|---|---|
git status | allow | Matches “Inspect the working tree”. |
git clean -fd | deny | Matches “Protect untracked files”. |
git log | none | Neither 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.
- Create a free workspace. Cloud Free includes 1,000 governed actions per workspace each month.
- Open Policies, choose Import YAML and upload
rules.yaml. - 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.
- 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
- Integrate your own harness.
- Look up rule fields or check command matching.
- Read the security model.
- Add a ready-made policy to a repository with
nodrail add. - Preview the run-history reference. Its gates and budgets require engine feature level 3.