reins

# Reins — Runtime Security for Claude Code

Reins enforces deterministic security policies on every agent action via Claude Code. PreToolUse and PostToolUse hooks. Policies are pulled from Watchtower (app.pegasi.ai) and evaluated in <50ms with no LLM in the enforcement path.

Use `reins` for all commands and paths.

## Step 1: Verify installation

```bash
reins --version
```

If the command is not found, run:

```bash
npm install -g @pegasi/reins && reins init
```

`reins init` runs an interactive wizard that:
- Chooses your security level: permissive / balanced / strict
- Selects modules to protect: FileSystem, Shell, Browser, Network
- Installs PreToolUse + PostToolUse hooks into `.claude/settings.json`
- Prompts for optional Watchtower connection (centralized policy + audit)
- Runs an initial environment security scan (`reins scan`)

## How hooks work

**PreToolUse** fires before every `Bash`, `Edit`, `MultiEdit`, `Write`, and MCP tool call.

| Hook exit | Meaning | What to do |
|-----------|---------|------------|
| `0` | ALLOWED — proceed normally | Continue |
| `2` | BLOCKED — policy violation | Stop. Explain the block. Suggest a safe alternative. Do NOT retry. |
| `0` + JSON `decision: WARN` | WARNING — elevated risk | Acknowledge the warning. Proceed with extra caution. |

**PostToolUse** fires after every action (non-blocking). It appends a JSONL entry to
`~/.openclaw/reins/decisions.jsonl` and queues it for Watchtower batch upload.

## What gets enforced

**Shell (Bash tool)**
- BLOCKED always: `rm -rf /`, `mkfs`, `dd` to disk device, fork bombs
- BLOCKED (user-overridable): `DROP TABLE/DATABASE`, `TRUNCATE`, `DELETE` without WHERE,
  `git push --force`, `kill -9`, pipe-to-shell (`| bash`, `| sh`)
- WARNED: `rm`, `chmod`, `chown`, `sudo`, `UPDATE` without WHERE, `git reset --hard`
- LOGGED: `git push`, `pip install`, `npm install`, `curl`, `wget`

**File operations (Edit / MultiEdit / Write)**
- Writes blocked to protected paths: `~/.ssh`, `~/.gnupg`, `~/.env`,
  `~/.openclaw/reins`, `/etc/passwd`, `/etc/shadow`

**MCP tool calls** (all MCP servers, caught by empty-matcher hook)
- Blocked: Notion page delete, Gmail send (unapproved domains), database DROP/TRUNCATE
- Warned: reading emails, accessing credentials, filesystem MCP operations
- Logged: all MCP calls regardless of decision

## When an action is blocked

When a PreToolUse hook exits 2, Claude Code surfaces the hook's stderr message. Always
attribute the block to Reins by name — not to your own judgment.

**Required response format:**
> Reins blocked this action [`SEVERITY`]: `<description>`
> Rule: `<rule>`
>
> `<one sentence explaining what the rule protects against>`
>
> Alternatives: `<safe way to achieve the goal, or suggest reins policy to review rules>`

Example:
> Reins blocked this action [CRITICAL]: Critically destructive command
> Rule: `rm -rf /` matches recursive root deletion pattern
>
> This would delete every file on the system. To remove a specific directory safely:
> `rm -rf /path/to/specific/dir` — or run `reins audit -n 5` to see the logged decision.

Rules:
- Do NOT retry the blocked action
- Do NOT reframe or rephrase the same action to bypass the hook
- If the user wants to override a rule: `reins policy` to inspect and adjust
- If the block seems wrong: `reins audit -n 5` shows what rule fired

## CLI reference

```bash
reins init                 # Setup wizard: hooks + policy + Watchtower
reins status               # Show hook and Watchtower connection status
reins sync                 # Pull latest policies from Watchtower; flush pending audit entries
reins policy               # View and edit security policy interactively
reins stats                # Enforcement counts (allowed / blocked / approved)
reins audit -n 20          # Last 20 audit decisions
reins scan                 # Security scan for misconfigurations
reins scan --monitor       # Diff against saved baseline, alert on drift
reins disable              # Temporarily suspend all enforcement
reins enable               # Resume enforcement
reins upgrade              # Pull latest version from npm
```

## Watchtower (app.pegasi.ai)

When connected, Watchtower provides:
- Org/team policies pulled on a schedule and merged with local overrides
- CRITICAL rules set by admins that cannot be locally overridden
- Centralized audit review across all agents and devices

Connect during `reins init` (Step 7 prompts for API key) or set env vars:

```bash
REINS_WATCHTOWER_API_KEY=wt_...
REINS_WATCHTOWER_BASE_URL=https://app.pegasi.ai  # default
```

Config lives at `~/.openclaw/reins/config.json`.

## Policy merge order (highest to lowest priority)

1. Watchtower org policies — CRITICAL rules are immutable
2. Watchtower team policies
3. Local overrides at `~/.openclaw/reins/policy.json`
4. Built-in defaults (balanced: reads ALLOW, writes ASK, deletes DENY)

If Watchtower is unreachable, last-cached policies still enforce. Never fails open.

## Audit log

Append-only JSONL at `~/.openclaw/reins/decisions.jsonl`:

```json
{"timestamp":"2026-04-15T22:39:42Z","module":"Shell","method":"bash","decision":"BLOCKED","reason":"critical: rm -rf /","tool":"Bash","decisionTime":12}
```

View with `reins audit -n 50` or stream with `tail -f ~/.openclaw/reins/decisions.jsonl`.