safe-rm

Email approval for risky rm commands. Built for AI coding agents on production servers.

---

The Problem

AI coding agents (Claude Code, Cursor, Copilot) can execute destructive commands on your server. One rm -rf gone wrong can wipe production data. You need a human-in-the-loop safety net that works without babysitting a terminal.

The Solution

safe-rm intercepts risky deletions and requires email approval before proceeding. It replaces rm on your server with a thin wrapper that detects dangerous commands, sends you an email with Approve/Deny buttons, and waits for your response before executing anything.

How It Works

 VPS (your server)                    Your Infrastructure
 ───────────────────                  ────────────────────

 AI Agent runs:
 rm -rf /var/www/data
        │
        ▼
 ┌─────────────┐    HMAC-signed     ┌──────────────────┐
 │   safe-rm    │ ──── POST ──────► │  Approval Server │
 │  (Python)    │                    │   (Express.js)   │
 │              │                    │                  │
 │  Polls for   │ ◄─── GET ──────── │  Creates request │
 │  status...   │    /status         │  with tokens     │
 └─────────────┘                    └────────┬─────────┘
        │                                    │
        │                              Webhook (POST)
        │                                    │
        │                                    ▼
        │                           ┌────────────────┐
        │                           │      n8n       │
        │                           │  (automation)  │
        │                           └────────┬───────┘
        │                                    │
        │                              Sends email
        │                                    │
        │                                    ▼
        │                           ┌────────────────┐
        │                           │  Your Inbox    │
        │                           │                │
        │                           │ [Approve] [Deny]
        │                           └────────┬───────┘
        │                                    │
        │                              Clicks link
        │                                    │
        │                                    ▼
        │                           ┌──────────────────┐
        │    status: approved        │  Approval Server │
        │ ◄────────────────────────  │  updates status  │
        │                           └──────────────────┘
        ▼
 Executes real /bin/rm
 (or exits with error
  if denied/expired)

Quick Start

1. Deploy the approval server

git clone https://github.com/DatafyingTech/safe-rm.git
cd safe-rm/server
npm install
cp ../examples/.env.example .env
# Edit .env with your domain, secret, and n8n webhook URL
node src/index.js

2. Install the client on your VPS

# On the VPS where your AI agent runs
sudo ./client/install.sh

The installer will prompt for your approval server URL and shared secret.

3. Set up email notifications

Import one of the n8n workflow templates into your n8n instance, configure your email credentials, and point the webhook URL to your server's .env.

That's it. The next time an AI agent (or anyone) runs a risky rm command, you'll get an email.

Features

• Risk detection -- catches recursive deletes, force flags, protected paths, glob patterns, and large file counts
• Hard-blocked paths -- /, ~, ., and .. are always blocked, no approval possible
• Protected path system -- configurable list of critical directories that require approval
• Safe patterns -- whitelist paths that should never trigger approval (build artifacts, temp files)
• Source IP filtering -- only require approval for specific SSH sessions (e.g., AI agent IPs)
• HMAC-SHA256 signatures -- all client-to-server requests are cryptographically signed
• Timing-safe token comparison -- prevents timing attacks on approval tokens
• One-time-use tokens -- each approve/deny link works exactly once
• Configurable expiry -- approval requests expire after a timeout (default: 10 minutes)
• Session stop -- remotely halt a session from your email
• Dry-run mode -- test what safe-rm would do without making API calls
• Claude Code hook system -- approve any tool call, not just rm (see Claude Code Integration)
• Auto-approve windows -- approve all actions for N minutes from your email

Architecture

The system has three components:

1. Client (client/safe-rm) -- Python script that replaces rm on the VPS
2. Server (server/) -- Express.js API that manages approval requests and tokens
3. Notifications (n8n-workflows/) -- n8n workflows that send approval emails

For a deep dive into the request lifecycle, security model, database schema, and API reference, see docs/ARCHITECTURE.md.

Configuration

The client reads configuration from /etc/safe-rm.conf (or ~/.safe-rm.conf) and environment variables. The server is configured via a .env file.

For a complete reference of all options, see docs/CONFIGURATION.md.

Claude Code Integration

safe-rm includes a general-purpose hook system for Claude Code that can intercept and require approval for any tool call -- not just rm commands. See docs/CLAUDE-CODE-INTEGRATION.md.

Documentation

Document	Description
Installation Guide	Step-by-step setup for server, client, and n8n
Configuration Reference	All server and client options
Architecture	System design, security model, API reference
Claude Code Integration	Hook system for Claude Code tool approvals

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

License

MIT