Permission Vending Machine (PVM)

Multi-channel approval system for AI agent permissions.

Gates sensitive operations (file deletion, git force-push, etc.) behind a human approver. Notifies via iMessage/SMS, Email, Discord, Telegram, or Slack — and enforces grants before running dangerous commands.

When to use

Use when an AI agent needs to perform an operation that could be destructive:

• Deleting files or directories
• Force-pushing to git repositories
• Moving files to trash outside the agent's workspace

Quick Setup

# 1. Install
git clone https://github.com/tylerdotai/permission-vending-machine.git
cd permission-vending-machine
pip install -e .

# 2. Configure
cp config.example.yaml config.yaml
# Edit config.yaml with your API keys

# 3. Start the daemon (macOS)
launchctl load ~/Library/LaunchAgents/ai.flume.pvm.plist

# 4. Agent requests permission
pvm request --scope "/tmp/build" --reason "cleaning artifacts" --duration 5

# 5. Approver approves via iMessage, email, or Discord link

# 6. Agent runs guarded command
safe-rm -rf /tmp/build

How it works

Agent → pvm request → Vault (pending) → Notify all channels
                                                ↓
                 Approver approves via any channel
                                                ↓
                 Grant created → Agent unblocks → safe-* command executes

Approval Methods

Method	How to approve
iMessage	Reply APPROVE (no token needed)
Email	Reply APPROVE in the approval email
Discord	Click "Click to approve" link
HTTP	curl http://host:7823/approve/<token>

Configuration

Key settings in config.yaml:

channels:
  sendblue:        # macOS only — iMessage via CLI
    enabled: true
    from_number: "+1..."
    approver_numbers: ["+1..."]
  email:           # cross-platform
    enabled: true
    imap_host: "imap.example.com"
    username: "user"
    password: "pass"
  discord:         # cross-platform
    enabled: true
    webhook_url: "https://discord.com/api/webhooks/..."
    http_approval_base: "http://your-server:7823"

CLI Commands

pvm request --scope <path> --reason <text> --duration <min>  # Request approval
pvm status --agent-id <id>                                    # List active grants
pvm revoke --grant-id <id>                                    # Revoke early
pvm log --limit 50                                           # Audit log
pvm serve --port 7823                                         # HTTP server
pvm approve-daemon --port 7823                               # Full daemon

Wrappers

Prepend safe- to guarded commands:

• safe-rm -rf /path — checks path scope grant
• safe-git-push --force — checks repo scope grant
• safe-trash /path — checks path scope grant

Platforms

• macOS: launchd service, Sendblue iMessage works
• Linux: systemd service, use Discord/email/Telegram for approvals
• Windows: NSSM/Task Scheduler, use Discord/email/Telegram

See docs/PLATFORMS.md for detailed setup per platform.

Links

• Repo: https://github.com/tylerdotai/permission-vending-machine
• Docs: PLATFORMS.md · ARCHITECTURE.md