Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

IronClaw’s channel system provides a unified interface for communicating with your agent through multiple platforms and protocols.

​
Architecture

Channels receive messages from external sources (CLI, messaging apps, HTTP webhooks) and convert them to a unified format for the agent to process. All responses flow back through the same channel. 
┌─────────────────────────────────────────────────────────────────────┐
│                         ChannelManager                              │
│                                                                     │
│   ┌──────────────┐   ┌─────────────┐   ┌─────────────┐             │
│   │ ReplChannel  │   │ HttpChannel │   │ WasmChannel │   ...       │
│   └──────┬───────┘   └──────┬──────┘   └──────┬──────┘             │
│          │                 │                 │                      │
│          └─────────────────┴─────────────────┘                      │
│                            │                                        │
│                   select_all (futures)                              │
│                            │                                        │
│                            ▼                                        │
│                     MessageStream                                   │
└─────────────────────────────────────────────────────────────────────┘

​
Available Channels

​
Native Channels

CLI (REPL) - Built-in interactive terminal interface. Always available.
  • Interactive command-line interface
  • Command history and completion
  • Debug mode toggle with /debug
HTTP Webhook - HTTP POST endpoint for programmatic access.
  • POST requests with JSON payloads
  • Webhook secret authentication
  • Optional synchronous responses
  • Rate limiting (60 req/min)
Signal - Native integration with Signal messenger via signal-cli.
  • Direct messages and group chats
  • DM pairing for access control
  • Typing indicators and status updates
  • Attachment support within sandbox
Web Gateway - Browser-based UI with rich features.
  • Real-time chat via SSE or WebSocket
  • Workspace/memory browser
  • Job management interface
  • OpenAI-compatible API proxy

​
WASM Channels

WASM channels are dynamically loaded at runtime from ~/.ironclaw/channels/: Telegram - Telegram Bot API integration.
  • Webhook or polling modes
  • DM pairing with approval codes
  • Group chat with @mention triggering
  • Markdown formatting support
Slack - Slack Events API integration.
  • App mentions and DMs
  • Thread support
  • Signature validation

​
Message Flow

​
Incoming Messages

  1. Receive - Channel receives external input (HTTP POST, WebSocket, Signal message)
  2. Parse - Convert to IncomingMessage with unified fields:
    • id - Unique message UUID
    • channel - Source channel name
    • user_id - Sender identifier
    • content - Message text
    • thread_id - Conversation thread (optional)
    • metadata - Channel-specific routing info
  3. Emit - Forward to agent loop via message stream

​
Outgoing Responses

  1. Generate - Agent creates OutgoingResponse:
    • content - Response text
    • thread_id - Reply thread (optional)
    • attachments - File paths (optional)
  2. Route - Channel uses stored metadata to target correct destination
  3. Send - Channel-specific API call (Telegram sendMessage, Slack chat.postMessage, etc.)

​
Status Updates

Channels can display real-time agent activity:
  • Thinking - Agent is processing (shown as typing indicator)
  • ToolStarted/ToolCompleted - Tool execution lifecycle
  • ToolResult - Preview of tool output (debug mode)
  • Status - General status messages
  • JobStarted - Sandbox job launched (with URL)
  • ApprovalNeeded - Tool requires user confirmation
  • AuthRequired/AuthCompleted - Extension authentication flow
Each channel decides how to render these (e.g., typing indicator, status message, or skip).

​
Access Control

All channels support three DM policies:

​
open

Allow all users. No restrictions. 
{
  "dm_policy": "open"
}

​
allowlist

Only accept messages from pre-approved users. Silent drop for others. 
{
  "dm_policy": "allowlist",
  "allow_from": ["+1234567890", "alice", "*"]
}

​
pairing (default)

Combines allowlist with interactive pairing. Unknown users receive a pairing code: 
To pair with this bot, run: ironclaw pairing approve telegram ABC12345
After approval, they’re added to the persistent allow list. 
{
  "dm_policy": "pairing",
  "allow_from": ["+1234567890"]
}

​
Owner Restriction

Set owner_id to lock the channel to a single user (overrides all DM policies): 
{
  "owner_id": "123456789"
}

​
Configuration Files

WASM channels use a .capabilities.json file to declare:
  • HTTP allowlist - Permitted API endpoints
  • Secrets - Required credentials (bot tokens, signing secrets)
  • Rate limits - Requests per minute/hour
  • Webhooks - Allowed paths and secret validation
  • Polling - Minimum interval for getUpdates-style APIs
Example: 
{
  "type": "channel",
  "name": "telegram",
  "capabilities": {
    "http": {
      "allowlist": [
        { "host": "api.telegram.org", "path_prefix": "/bot" }
      ],
      "rate_limit": {
        "requests_per_minute": 30
      }
    },
    "secrets": {
      "allowed_names": ["telegram_*"]
    }
  }
}

​
Channel Lifecycle

  1. on_start() - Initialize, register webhooks, validate tokens
  2. start() - Begin listening for messages (returns MessageStream)
  3. respond() - Send response back to user
  4. send_status() - Broadcast status updates
  5. health_check() - Verify channel is operational
  6. shutdown() - Graceful cleanup (delete webhooks, close connections)

​
Thread Support

Channels use thread_id for conversation continuity:
  • Telegram - Generates deterministic UUID from sender/group ID
  • Slack - Uses Slack’s native thread_ts
  • Signal - Uses source_uuid or phone-based UUID
  • HTTP - Optional thread_id in request payload
  • Web Gateway - WebSocket connection or SSE client ID
The agent’s maybe_hydrate_thread loads conversation history when a thread ID matches a stored session.

​
Rate Limiting

Channels enforce rate limits to prevent abuse:
  • HTTP Webhook - 60 requests/minute
  • Telegram - 30 API calls/minute
  • Slack - 50 API calls/minute
  • Web Gateway - 30 chat messages/minute
Exceeding limits returns HTTP 429 (Too Many Requests).

​
Security

​
Webhook Secrets

HTTP-based channels require secret validation:
  • HTTP - HTTP_WEBHOOK_SECRET in request body
  • Telegram - X-Telegram-Bot-Api-Secret-Token header
  • Slack - HMAC signature validation with signing secret
The host validates secrets before forwarding to WASM channels.

​
Sandboxing (WASM Channels)

WASM channels run in a secure sandbox:
  • No filesystem access (except workspace via host APIs)
  • HTTP limited to declared allowlist
  • No raw credential access (host injects tokens via URL placeholders)
  • Emit rate limits prevent message floods

​
Path Validation

Attachment paths are validated to prevent traversal attacks: 
// Only paths within ~/.ironclaw/ are allowed
validate_attachment_paths(&["/home/user/.ironclaw/files/report.pdf"])

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us