Local configuration

Failproof AI keeps what a repository can commit — hook wiring, policy parameters, custom policies — apart from machine state such as credentials, installed packs, and the daemon.

Choose a scope

A scope decides where the hooks are wired, and which configuration file you write parameters and custom policy paths into:

User applies across projects on this machine.
Project belongs to the repository and can be committed.
Local overrides one project for one user and should remain gitignored.

failproofai policies --install --cli claude --scope project   # wire hooks for this repository
failproofai policies --install --cli claude --scope user      # or for every project on this machine
failproofai policies

Not every harness supports local scope; the CLI rejects a scope the selected harness cannot represent. Which pack policies are on is not scoped. The switch is recorded with the installed pack, so failproofai policies add <name> turns a policy on for the whole machine, whatever --scope says.

Scope	Policy configuration file
Project	`<project>/.failproofai/policies-config.json`
Local	`<project>/.failproofai/policies-config.local.json`
User	`~/.failproofai/policies-config.json`

Policy parameters use the first scope that defines parameters for that policy, in project → local → user order. Explicit custom policy paths use the first scope that defines them.

Configure policy parameters

Dashboard
CLI

Open the policy in the local dashboard, edit its supported parameters, and save in the selected scope. Run a matching and non-matching agent action, then inspect the decision in Observe → policy.

Edit the selected scope’s policies-config.json, then run failproofai policies: it warns about a policyParams entry naming a policy no installed pack carries. It does not check the keys inside an entry, so check their spelling against the table below.

{
  "policyParams": {
    "block-rm-rf": {
      "allowPaths": ["/tmp/build-output"]
    }
  }
}

failproofai policies

Parameters the Failproof AI policies accept

Each policy validates its own parameter types.

Policy	Parameter	Type and default
`sanitize-api-keys`	`additionalPatterns`	`pattern[]`, `[]`; entries contain `regex` and `label`
`block-read-outside-cwd`	`allowPaths`	`string[]`, `[]`
`block-sudo`	`allowPatterns`	`string[]`, `[]`
`block-rm-rf`	`allowPaths`	`string[]`, `[]`
Infrastructure blockers	`allowPatterns`	`string[]`, `[]`
`block-secrets-write`	`additionalPatterns`	`string[]`, `[]`
`block-push-master`	`protectedBranches`	`string[]`, `["main", "master"]`
`block-work-on-main`	`protectedBranches`	`string[]`, `["main", "master"]`
`prefer-package-manager`	`allowed`, `blocked`	`string[]`, `[]`
`warn-large-file-write`	`thresholdKb`	`number`, `1024`
`require-push-before-stop`	`remote`, `baseBranch`	`string`, `"origin"`; `string`, `"main"`
`require-pr-before-stop`	`baseBranch`	`string`, `"main"`
`require-no-conflicts-before-stop`	`baseBranch`	`string`, `"main"`

An allow pattern broadens what an agent may do. Test the exact tokenization and command variants on the target harness before deploying it across a fleet.

Understand the machine files

~/.failproofai contains separate files for separate trust boundaries:

Path	Purpose
`config.json`	Non-secret daemon, audit, and telemetry settings
`credentials.json`	Cloud credentials; stored with owner-only permissions
`policies-config.json`	User-scope parameters and explicit custom policy paths
`policies/`	User convention policies, installed packs and which of their policies are on, and Cloud-managed policy artifacts
`hook-activity/`	Local policy decision log
`state/`	Daemon spool, health, pause, and runtime state

Use FAILPROOFAI_HOME to relocate the complete machine layout for a container or isolated test. Do not relocate individual state directories independently.

Never commit credentials.json. Commit project policy configuration and project convention policies only after reviewing them as enforcement code.

Connect your agents

Jev reference

Reference

HTTP API

Choose a scope

Configure policy parameters

Parameters the Failproof AI policies accept

Understand the machine files

​Choose a scope

​Configure policy parameters

​Parameters the Failproof AI policies accept

​Understand the machine files

Choose a scope

Configure policy parameters

Parameters the Failproof AI policies accept

Understand the machine files