> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started
title: Guida introduttiva
description: "Installa failproofai, abilita le policy e lascia che i tuoi agent funzionino in modo affidabile"
icon: rocket
------------
## Requisiti
* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0 (opzionale - necessario solo per compilare dal codice sorgente)
***
## Installazione
```bash npm theme={null}
npm install -g failproofai
```
```bash bun theme={null}
bun add -g failproofai
```
***
## Avvio rapido
Le policy sono regole che vengono eseguite prima e dopo ogni chiamata di strumento dell'agent. Catturano comandi distruttivi, fughe di segreti e altri modi di fallimento prima che causino danni.
```bash theme={null}
failproofai policies --install
```
Questo scrive voci di hook nei tuoi agent CLI installati (il file `~/.claude/settings.json` di Claude Code, il file `~/.codex/hooks.json` di OpenAI Codex, il file `~/.copilot/hooks/failproofai.json` di GitHub Copilot CLI, il file `~/.cursor/hooks.json` di Cursor Agent, lo shim del plugin generato di OpenCode in `~/.config/opencode/plugins/failproofai.mjs` più una voce di registrazione nell'array `plugin` di `~/.config/opencode/opencode.json`, il file `~/.pi/agent/settings.json` di Pi, o il file `~/.hermes/config.yaml` di Hermes). Quando è presente più di uno, ti verrà chiesto; passa `--cli claude codex copilot cursor opencode pi hermes` (qualsiasi sottoinsieme) per saltare la richiesta.
Il supporto per GitHub Copilot CLI, Cursor Agent, OpenCode e Pi è in **beta** — installa con `--cli copilot`, `--cli cursor`, `--cli opencode` o `--cli pi`. Hermes (hermes-agent, un gateway Slack/Telegram) si installa con ambito utente con `--cli hermes` ed è **anche** una fonte di audit offline.
```bash theme={null}
failproofai policies --install --scope project
failproofai policies --install --cli codex --scope project
failproofai policies --install --cli copilot --scope project
failproofai policies --install --cli cursor --scope project
failproofai policies --install --cli opencode --scope project
failproofai policies --install --cli pi --scope project
failproofai policies --install --cli hermes --scope user
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
```
```bash theme={null}
failproofai policies
```
Mostra ogni policy, se è abilitata e eventuali parametri configurati.
```bash theme={null}
failproofai
```
Apre una dashboard locale su `http://localhost:8020` dove puoi sfogliare le sessioni, ispezionare le chiamate di strumento e gestire le policy.
Avvia Claude Code come al solito. Se l'agent prova a fare qualcosa di rischioso, failproofai lo intercetta automaticamente. Lascialo in esecuzione incustodito e rivedi quello che è successo nella dashboard.
***
## Come funzionano le policy
Ogni volta che un agent esegue uno strumento, Claude Code chiama failproofai come sottoprocesso:
```text theme={null}
Claude Code → failproofai --hook PreToolUse → legge JSON da stdin
valuta le policy
scrive la decisione su stdout
```
Ogni policy restituisce una di tre decisioni:
* **allow** - l'agent procede normalmente
* **deny** - l'azione viene bloccata, all'agent viene spiegato il motivo
* **instruct** - contesto aggiuntivo viene aggiunto al prompt dell'agent
Le policy vengono eseguite nel tuo processo locale. Nulla viene inviato a un servizio remoto.
***
## Configura policy di team con policy basate su convenzione
Il modo più veloce per stabilire standard di qualità in tutto il team è la convenzione `.failproofai/policies/`. Inserisci file di policy in questa directory e vengono caricati automaticamente — nessun flag, nessun cambio di configurazione, nessun comando di installazione.
```bash theme={null}
mkdir -p .failproofai/policies
```
Copia gli esempi iniziali o scrivi i tuoi:
```bash theme={null}
cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
```
O creane uno nuovo:
```js theme={null}
// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";
customPolicies.add({
name: "test-before-commit",
match: { events: ["PreToolUse"] },
fn: async (ctx) => {
if (ctx.toolName !== "Bash") return allow();
if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
return instruct("Esegui i test prima di fare il commit.");
}
return allow();
},
});
```
```bash theme={null}
git add .failproofai/policies/
git commit -m "Aggiungi policy di qualità del team"
```
Ogni membro del team che ha failproofai installato raccoglie automaticamente queste policy. Nessuna configurazione per sviluppatore necessaria.
Fai il commit di `.failproofai/policies/` nel tuo repository in modo che tutto il team condivida gli stessi standard. Man mano che il tuo team scopre nuovi modi di fallimento, aggiungi policy e fai il push — ognuno riceve l'aggiornamento al prossimo `git pull`. Nel tempo queste policy diventano uno standard di qualità vivente che continua a migliorare.
***
## Archiviazione dei dati
Tutta la configurazione e i log rimangono sulla tua macchina:
| Percorso | Cosa archivia |
| ----------------------------------------- | ------------------------------------------------- |
| `~/.failproofai/policies-config.json` | Configurazione globale delle policy |
| `~/.failproofai/hook-activity.jsonl` | Cronologia dell'esecuzione degli hook |
| `~/.failproofai/hook.log` | Log di debug per errori degli hook personalizzati |
| `.failproofai/policies-config.json` | Configurazione per progetto (committed) |
| `.failproofai/policies-config.local.json` | Personalizzazioni personali (gitignored) |
***
## Disinstallazione
```bash theme={null}
failproofai policies --uninstall
```
Rimuove le voci degli hook da `~/.claude/settings.json`. I file di configurazione in `~/.failproofai/` vengono conservati.
***
## Passaggi successivi
Ambiti e formato del file di configurazione
Tutte le 26 policy con parametri
Scrivi le tue policy in JavaScript
Monitora le sessioni e rivedi l'attività delle policy