# Try APF locally

> Write a YAML rule, inspect its decisions, connect the local Claude Code hook and test your policy in CI. No Cloud account required.

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.

```sh
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`](https://nodrail.com/docs/cli), 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`.

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

```sh
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`.

```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
```

```sh
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.

```json
{
  "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.

```sh
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`.

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

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

```sh
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.

```sh
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](https://app.nodrail.com/signup). 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](https://nodrail.com/docs/agent-plugins). 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](https://nodrail.com/docs/cloud#policies).

## Where to go from here

- [Integrate your own harness](https://nodrail.com/docs/library#connect-a-custom-harness).
- [Look up rule fields](https://nodrail.com/docs/rules) or [check command matching](https://nodrail.com/docs/commands-and-tools).
- [Read the security model](https://github.com/Nodrail/nodrail-js/blob/main/packages/policy-engine/docs/security-model.md).
- [Add a ready-made policy to a repository](https://nodrail.com/docs/playbooks) with `nodrail add`.
- [Preview the run-history reference](https://nodrail.com/docs/runs). Its gates and budgets require engine feature level 3.
