ironclaw pairing

Manage DM pairing requests for communication channels

ironclaw pairing

Manage pairing requests for direct message channels like Telegram and Slack. When someone sends a DM to your agent from an unknown sender, a pairing request is created that must be approved before the agent will respond.

Subcommands

• list - List pending pairing requests
• approve - Approve a pairing request by code

---

ironclaw pairing list

List all pending pairing requests for a specific channel.

Syntax

ironclaw pairing list <CHANNEL> [FLAGS]

Arguments

<CHANNEL>

Channel name (e.g., telegram, slack, discord).

Flags

--json

Output as JSON instead of human-readable format.

Examples

# List Telegram pairing requests
ironclaw pairing list telegram

# List Slack pairing requests
ironclaw pairing list slack

# Get JSON output
ironclaw pairing list telegram --json

Output

Human-readable format:

Pairing requests (3):
  ABC12345  user123  username=alice, first_name=Alice  2024-01-15 14:23:45
  DEF67890  user456  username=bob                      2024-01-15 15:30:12
  GHI11121  user789  first_name=Charlie                2024-01-15 16:15:33

Columns:

• Code - Pairing code to use with approve
• ID - Channel-specific user ID
• Metadata - Additional information (username, name, etc.)
• Created - Timestamp when request was created

No pending requests:

No pending telegram pairing requests.

JSON format:

[
  {
    "code": "ABC12345",
    "id": "user123",
    "channel": "telegram",
    "created_at": "2024-01-15T14:23:45Z",
    "meta": {
      "username": "alice",
      "first_name": "Alice"
    }
  },
  {
    "code": "DEF67890",
    "id": "user456",
    "channel": "telegram",
    "created_at": "2024-01-15T15:30:12Z",
    "meta": {
      "username": "bob"
    }
  }
]

---

ironclaw pairing approve

Approve a pairing request using its code.

Syntax

ironclaw pairing approve <CHANNEL> <CODE>

Arguments

<CHANNEL>

Channel name (e.g., telegram, slack).

<CODE>

Pairing code from the list output (e.g., ABC12345).

Examples

# Approve Telegram pairing request
ironclaw pairing approve telegram ABC12345

# Approve Slack pairing request
ironclaw pairing approve slack XYZ99999

Output

Success:

Approved telegram sender user123.

Code not found:

Error: No pending pairing request found for code: ABC12345

Rate limited:

Error: Too many failed approve attempts. Wait a few minutes before trying again.

How Pairing Works

1. Unknown Sender Messages You

When someone sends a DM to your agent from a channel you’ve configured:

Unknown Telegram user @alice sends: "Hello!"

2. Pairing Request Created

The agent creates a pairing request and responds with a code:

Your pairing code is: ABC12345

Ask the agent owner to approve with:
  ironclaw pairing approve telegram ABC12345

3. You Approve the Request

ironclaw pairing list telegram
# Shows: ABC12345  user123  username=alice ...

ironclaw pairing approve telegram ABC12345
# Approved telegram sender user123.

4. Sender Can Now Chat

The sender’s next message will be processed normally:

Alice: "Hello!"
Agent: "Hi Alice! How can I help you today?"

Pairing Request Lifecycle

Creation

• Created when an unknown sender messages the agent
• Includes metadata: username, display name, etc.
• Generates an 8-character alphanumeric code
• Valid indefinitely until approved or sender is blocked

Approval

• Marks the sender as trusted
• Removes the pending request
• Future messages from this sender are processed normally

Re-requesting

If the same sender messages again before approval:

• Extends the existing request timestamp
• Returns the same pairing code
• Does not create a duplicate request

Security Features

Rate Limiting

Approval attempts are rate-limited to prevent brute-force attacks:

• Too many failed attempts trigger a cooldown period
• Cooldown is user-specific (per your IronClaw instance)

Code Format

Pairing codes are:

• 8 characters long
• Alphanumeric (A-Z, 0-9)
• Case-insensitive
• Cryptographically random

Automatic Cleanup

Old pairing requests are automatically cleaned up after:

• 30 days of inactivity (configurable)
• Approval
• Manual deletion

Storage Location

Pairing data is stored in:

~/.ironclaw/pairing/<channel>.json

Example: ~/.ironclaw/pairing/telegram.json

File Format

{
  "pending": [
    {
      "id": "user123",
      "code": "ABC12345",
      "created_at": "2024-01-15T14:23:45Z",
      "meta": {
        "username": "alice",
        "first_name": "Alice"
      }
    }
  ],
  "approved": [
    "user456",
    "user789"
  ],
  "blocked": []
}

Common Workflows

Daily Pairing Check

# Check for new pairing requests
ironclaw pairing list telegram

# Approve trusted users
ironclaw pairing approve telegram ABC12345

Bulk Approval

# Get JSON list
ironclaw pairing list telegram --json > requests.json

# Review and approve
cat requests.json | jq -r '.[] | .code' | while read code; do
  ironclaw pairing approve telegram $code
done

Monitoring Script

#!/bin/bash
# check-pairings.sh - Monitor for new pairing requests

CHANNELS=("telegram" "slack")

for channel in "${CHANNELS[@]}"; do
  count=$(ironclaw pairing list $channel --json | jq 'length')
  if [ $count -gt 0 ]; then
    echo "$count pending $channel pairing request(s)"
    ironclaw pairing list $channel
  fi
done

Channel-Specific Metadata

Telegram

{
  "username": "alice",
  "first_name": "Alice",
  "last_name": "Smith"
}

Slack

{
  "user_name": "alice",
  "real_name": "Alice Smith",
  "team_id": "T123456"
}

Discord

{
  "username": "alice#1234",
  "discriminator": "1234",
  "global_name": "Alice"
}

Troubleshooting

”No pending pairing requests”

Either:

• No one has messaged your agent from unknown accounts, or
• All requests have been approved/expired

Test by messaging your agent from a new account.

”Pairing file not found”

The channel may not be configured:

ironclaw doctor

Check your .env file for channel configuration.

”Code not found”

Possible causes:

• Typo in the code (codes are case-insensitive)
• Request already approved
• Request expired or manually deleted

List current requests:

ironclaw pairing list <channel>

“Rate limited”

Too many failed approval attempts. Wait a few minutes and try again.

Manual Pairing File Management

You can manually edit pairing files if needed:

# View pairing file
cat ~/.ironclaw/pairing/telegram.json

# Edit with your editor
vim ~/.ironclaw/pairing/telegram.json

# Validate JSON
jq . ~/.ironclaw/pairing/telegram.json

Warning: Manual edits can break pairing functionality. Use the CLI commands when possible.

Privacy Considerations

• Pairing requests include user metadata (usernames, names)
• This data is stored locally in plaintext
• Consider the sensitivity of stored metadata
• Regularly clean up old pairing data

Related Commands

• onboard —channels-only - Configure communication channels
• config - View channel configuration