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

# Primeros pasos

> Instala failproofai, activa las políticas y deja que tus agentes funcionen de forma confiable

## Requisitos

* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0 (opcional — solo necesario para compilar desde el código fuente)

***

## Instalación

<CodeGroup>
  ```bash npm theme={null}
  npm install -g failproofai
  ```

  ```bash bun theme={null}
  bun add -g failproofai
  ```
</CodeGroup>

***

## Inicio rápido

<Steps>
  <Step title="Activa las políticas">
    Las políticas son reglas que se ejecutan antes y después de cada llamada a una herramienta del agente. Detectan comandos destructivos, filtraciones de secretos y otros modos de fallo antes de que causen daño.

    ```bash theme={null}
    failproofai policies --install
    ```

    Esto escribe entradas de hooks en los CLIs de agentes instalados (el `~/.claude/settings.json` de Claude Code, el `~/.codex/hooks.json` de OpenAI Codex, el `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI, el `~/.cursor/hooks.json` de Cursor Agent, el shim de plugin generado de OpenCode en `~/.config/opencode/plugins/failproofai.mjs` junto con una entrada de registro en el array `plugin` de `~/.config/opencode/opencode.json`, el `~/.pi/agent/settings.json` de Pi, o el `~/.hermes/config.yaml` de Hermes). Si hay más de uno presente, se te pedirá que elijas; pasa `--cli claude codex copilot cursor opencode pi hermes` (cualquier subconjunto) para omitir la pregunta.

    El soporte para GitHub Copilot CLI, Cursor Agent, OpenCode y Pi es **beta** — instala con `--cli copilot`, `--cli cursor`, `--cli opencode` o `--cli pi`. Hermes (hermes-agent, una puerta de enlace para Slack/Telegram) se instala con alcance de usuario mediante `--cli hermes` y es **también** una fuente de auditoría sin conexión.

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

  <Step title="Verifica la instalación">
    ```bash theme={null}
    failproofai policies
    ```

    Muestra todas las políticas, si están habilitadas y los parámetros configurados.
  </Step>

  <Step title="Abre el panel de control">
    ```bash theme={null}
    failproofai
    ```

    Abre un panel de control local en `http://localhost:8020` donde puedes explorar sesiones, inspeccionar llamadas a herramientas y gestionar políticas.
  </Step>

  <Step title="Ejecuta tu agente">
    Inicia Claude Code como de costumbre. Si el agente intenta algo arriesgado, failproofai lo intercepta automáticamente. Déjalo correr desatendido y revisa lo que ocurrió en el panel de control.
  </Step>
</Steps>

***

## Cómo funcionan las políticas

Cada vez que un agente ejecuta una herramienta, Claude Code llama a failproofai como subproceso:

```text theme={null}
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
```

Cada política devuelve una de tres decisiones:

* **allow** — el agente continúa con normalidad
* **deny** — la acción es bloqueada y se le indica al agente el motivo
* **instruct** — se añade contexto adicional al prompt del agente

<Note>
  Las políticas se ejecutan en tu proceso local. No se envía nada a un servicio remoto.
</Note>

***

## Configura políticas de equipo con políticas basadas en convenciones

La forma más rápida de establecer estándares de calidad en tu equipo es la convención `.failproofai/policies/`. Coloca archivos de políticas en este directorio y se cargan automáticamente — sin flags, sin cambios de configuración, sin comandos de instalación.

<Steps>
  <Step title="Crea el directorio de políticas">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="Añade archivos de políticas">
    Copia los ejemplos de inicio o escribe los tuyos propios:

    ```bash theme={null}
    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
    ```

    O crea uno nuevo:

    ```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("Run tests before committing.");
        }
        return allow();
      },
    });
    ```
  </Step>

  <Step title="Confirma los cambios en git">
    ```bash theme={null}
    git add .failproofai/policies/
    git commit -m "Add team quality policies"
    ```

    Cada miembro del equipo que tenga failproofai instalado recibirá estas políticas automáticamente. No se necesita configuración por desarrollador.
  </Step>
</Steps>

<Tip>
  Confirma `.failproofai/policies/` en tu repositorio para que todo el equipo comparta los mismos estándares. A medida que tu equipo descubra nuevos modos de fallo, añade políticas y haz push — todos recibirán la actualización en su próximo `git pull`. Con el tiempo, estas políticas se convierten en un estándar de calidad vivo que no deja de mejorar.
</Tip>

***

## Almacenamiento de datos

Toda la configuración y los registros permanecen en tu máquina:

| Ruta                                      | Qué almacena                                                |
| ----------------------------------------- | ----------------------------------------------------------- |
| `~/.failproofai/policies-config.json`     | Configuración global de políticas                           |
| `~/.failproofai/hook-activity.jsonl`      | Historial de ejecución de hooks                             |
| `~/.failproofai/hook.log`                 | Registro de depuración para errores de hooks personalizados |
| `.failproofai/policies-config.json`       | Configuración por proyecto (confirmada en git)              |
| `.failproofai/policies-config.local.json` | Sobreescrituras personales (en gitignore)                   |

***

## Desinstalación

```bash theme={null}
failproofai policies --uninstall
```

Elimina las entradas de hooks de `~/.claude/settings.json`. Los archivos de configuración en `~/.failproofai/` se conservan.

***

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Configuración" icon="gear" href="/es/configuration">
    Alcances y formato del archivo de configuración
  </Card>

  <Card title="Políticas integradas" icon="shield" href="/es/built-in-policies">
    Las 26 políticas con sus parámetros
  </Card>

  <Card title="Políticas personalizadas" icon="code" href="/es/custom-policies">
    Escribe tus propias políticas en JavaScript
  </Card>

  <Card title="Monitor de agentes" icon="chart-line" href="/es/dashboard">
    Supervisa sesiones y revisa la actividad de las políticas
  </Card>
</CardGroup>