Device Pairing

What it is: A security gate. Strangers can’t just message your bot and get it to do stuff.

How it works: Unknown sender messages you → bot sends a pairing code → you approve (or deny) → they’re in (or out).

Why This Matters

You’re giving an AI shell access to your machine. Maybe browser control. Maybe your files.

You don’t want randos in there.

Pairing is the fence. Keep it up.

How Pairing Works

Someone you don’t know messages your bot
Bot generates a short code (expires in 1 hour)
Bot sends them the code, ignores their message
You check pending requests:
```
moltbot pairing list whatsapp
```

You approve or deny:


moltbot pairing approve whatsapp abc123
# or
moltbot pairing deny whatsapp abc123

If approved, they can chat. If denied, they stay blocked.

Pairing Policies

You’ve got options:

`pairing` (Default, Recommended)

Unknown senders get a code. You decide.


{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    }
  }
}

`allowlist` (Strictest)

Only people in your allowlist can DM. No codes, no exceptions.


{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+1234567890", "+0987654321"]
    }
  }
}

`open` (Don’t Do This)

Anyone can message your bot. No approval needed.

Only use this if: you fully understand the security implications and you’re okay with prompt injection risks.


{
  "channels": {
    "whatsapp": {
      "dmPolicy": "open",
      "allowFrom": ["*"]  // Explicit opt-in required
    }
  }
}

`disabled` (Nuclear Option)

Bot ignores all DMs. Only works in groups.


{
  "channels": {
    "whatsapp": {
      "dmPolicy": "disabled"
    }
  }
}

Group Chat Pairing

Groups work differently. You can:

Require mentions (recommended):


{
  "channels": {
    "whatsapp": {
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Allow specific groups only:


{
  "channels": {
    "whatsapp": {
      "groups": {
        "120363012345678900@g.us": { "requireMention": false }
      }
    }
  }
}

Get group IDs from moltbot channels list.

Pairing Files

Approved pairings live here:


~/.moltbot/credentials/whatsapp-allowFrom.json
~/.moltbot/credentials/telegram-allowFrom.json

These merge with your config’s allowFrom list.

Managing Approvals

List pending requests


moltbot pairing list whatsapp

Shows codes, who sent them, when they expire.

Approve someone


moltbot pairing approve whatsapp abc123

Deny someone


moltbot pairing deny whatsapp abc123

Clear all pending


moltbot pairing clear whatsapp

Revoke an approval

Remove them from allowFrom in config or delete from the credential file, then restart the Gateway.

Security Tips

Start strict, loosen later — Use pairing or allowlist by default
Groups need mentions — requireMention: true everywhere except trusted family groups
Don’t go open — Seriously, prompt injection is real
Audit regularly — moltbot security audit --deep

Multi-User Setup

Running this for family/team? Isolate sessions:


{
  "session": {
    "dmScope": "per-channel-peer"
  }
}

Prevents context bleeding between users.

Troubleshooting

Pairing code not showing up

Check Gateway logs: moltbot logs
Verify channel is connected: moltbot channels list

Approved user still can’t chat

Restart Gateway: moltbot gateway restart
Check allowlist file exists and is readable

Pairing codes expired

They last 1 hour. User needs to send another DM to get a fresh code.

What’s Next

Questions? Discord • GitHub