pi-gateway

Multi-platform chat bridge for pi — connect your AI agent to Telegram, Discord, Slack, and more. Real-time streaming, per-chat sessions, background tasks, and role-based access control.

Fork of 0xKobold/pi-gateway with config-based UID allowlisting.

Features

• Multi-platform adapters — Discord, Telegram, Slack, Twitch, WhatsApp, WebSocket
• Real-time streaming — responses appear token-by-token via live message editing
• Per-chat sessions — isolated conversations with configurable reset policies (daily / idle)
• Background tasks — spawn async work from chats, results delivered when ready
• Allowlist security — DB-based and config-file pre-approved UIDs, admin roles, tool access policies
• Detached daemon mode — /gateway start -d or pi-gateway start -d keeps the gateway alive after pi closes
• HTTP + WebSocket API — connect external clients, send prompts, receive streaming responses
• pi-native — runs as a pi extension with /gateway slash commands and registered tools

Installation

Install from npm (recommended):

pi install npm:@gamalan/pi-gateway

Or clone and build manually:

git clone https://github.com/gamalan/pi-gateway.git
cd pi-gateway
npm install && npm run build
pi install .

Requires pi coding agent (@earendil-works/pi-coding-agent >= 0.80.3) and @sinclair/typebox >= 0.32.0.

Quick Start

# Start the gateway
/gateway start

# Check status
/gateway status

# Stop
/gateway stop

The gateway starts on http://localhost:3847 by default. See /gateway config for current settings.

Configuration

Configuration lives at ~/.pi/gateway/config.json:

{
  "port": 3847,
  "host": "localhost",
  "tokens": [],                    // Bearer tokens for API auth (empty = allow all)
  "corsOrigins": ["*"],
  "enableWebSocket": true,
  "enableHttp": true,
  "security": {
    "allowAll": true,              // false = enforce allowlist
    "requirePairing": false,
    "allowedUids": {},             // pre-approved users (see Security)
    "adminUids": {},              // users with full access (see Admin Users)
    "rateLimit": {
      "maxRequests": 60,
      "windowMs": 60000
    }
  },
  "sessions": {
    "resetPolicy": "idle",         // "daily" | "idle" | "both"
    "dailyHour": 4,                // hour (0-23) for daily reset
    "idleMinutes": 1440            // minutes before idle reset
  },
  "platforms": {
    "discord": {
      "enabled": true,
      "botToken": "your-token",
      "guildId": "optional-guild-id"
    },
    "twitch": {
      "enabled": true,
      "clientId": "your-client-id",
      "clientSecret": "your-secret",
      "channels": ["channel-name"]
    },
    "telegram": {
      "enabled": true,
      "token": "your-bot-token",
      "webhookUrl": "https://..."  // omit for long polling
    },
    "slack": {
      "enabled": true,
      "webhookUrl": "https://...",
      "botToken": "optional-bot-token"
    },
    "whatsapp": {
      "enabled": true,
      "sessionPath": "~/.pi/whatsapp-session",
      "printQr": true
    }
  }
}

When the gateway starts for the first time with no config file, it automatically seeds ~/.pi/gateway/config.json from the default template shipped with the package. You can also find it at node_modules/pi-gateway/config/config.default.json.

Telegram: webhook vs long polling

The gateway auto-detects the mode based on whether webhookUrl is set:

| webhookUrl | Mode | How it works | |---|---|---| | Set | Webhook | Telegram POSTs updates to /webhook/telegram on the gateway's HTTP server. Lowest latency, requires a public URL. | | Omitted | Long polling | The gateway opens a persistent connection to Telegram's getUpdates endpoint (30s timeout). Telegram holds it open and returns immediately when a message arrives — near-real-time, no public URL needed. |

Both modes are real-time. Long polling is NOT interval-based — it keeps one connection alive at all times.

Security

Allowlist (DB)

Manage users at runtime via /gateway commands:

# List allowlisted users
/gateway allow

# Add a user
/gateway allow discord 123456789

# Revoke a user (via tool or directly)

Config-file pre-approved UIDs

Skip pairing entirely by listing UIDs in the security block of config.json:

{
  "security": {
    "allowAll": false,
    "allowedUids": {
      "discord": ["123456789", "987654321"],
      "telegram": ["1234567890"],
      "*": ["cross-platform-admin"]
    },
    "adminUids": {
      "discord": ["123456789"],
      "*": ["cross-platform-admin-uid"]
    },
    "rateLimit": {
      "maxRequests": 60,
      "windowMs": 60000
    }
  }
}

• Platform-specific keys match that platform only
• The "*" wildcard matches any platform
• Users in this list are auto-allowed on first contact — no pairing code needed
• adminUids grants full unrestricted access (bypasses all tool policies)
• All security settings live in the main config.json — no separate security file

Admin Users

Admin users have full unrestricted access — they bypass all tool policies and can use every tool pi offers (bash, write, edit, subagent, etc.).

Admins can be set at runtime or via config's security.adminUids block:

{
  "security": {
    "adminUids": {
      "discord": ["123456789"],
      "*": ["cross-platform-admin-uid"]
    }
  }
}

# List all admins (DB + config)
/gateway admin list

# Grant admin to a user on a specific platform
/gateway admin add discord 123456789

# Grant admin on ALL platforms
/gateway admin add * 123456789

# Revoke admin
/gateway admin remove discord 123456789

Admin users are listed in the status panel and their messages carry a "FULL ACCESS" guard.

Tool Policy

By default, external users are restricted to read-only tools when their messages reach pi: they can search code, inspect files, and ask questions, but cannot write files, execute shell commands, spawn subagents, or modify system state.

The policy is enforced via a system directive prepended to every forwarded message. It is tunable per platform, per user, or globally.

Default allowed tools: read, web_search, fetch_content, fffind, ffgrep, module_report, read_symbol, code search tools, lsp_diagnostics, lsp_navigation, image_generate, gateway_*

Default denied tools: bash, write, edit, subagent, todo, goal_complete, mcp, ast_grep_replace, agent_browser, wait, intercom, wiki_*, lens_diagnostics

Managing Policies

# List all explicit policies
/gateway tool-policy list

# See the default baseline
/gateway tool-policy defaults

# Allow bash for a specific user
/gateway tool-policy set discord U123456 bash allow

# Deny write for all users on Discord
/gateway tool-policy set discord * write deny

# Allow everything for an admin user (glob)
/gateway tool-policy set * admin-uid * allow

# Remove a policy by ID
/gateway tool-policy remove 3

# Reset all custom policies to defaults
/gateway tool-policy reset

Policies can also be managed from within pi sessions via the gateway_tool_policy tool.

Resolution order (highest wins): user-specific > platform-specific > global. Ties break deny-first (secure by default). The * glob matches any tool name. Admin users always bypass all restrictions.

Note: All security configuration (allowlist, admin UIDs, rate limits) lives in the security block of ~/.pi/gateway/config.json. There is no separate security config file. On first run, the gateway auto-seeds a complete default config so you don't have to write one from scratch.

Pairing Flow

When requirePairing is enabled and a user is not in the allowlist:

1. User sends a message → blocked, receives a pairing code
2. Admin approves with /gateway pair <code>
3. User is added to the DB allowlist

Commands

| Command | Description | |---------|-------------| | /gateway start [port] | Start the gateway | | /gateway stop | Stop the gateway | | /gateway restart | Restart the gateway | | /gateway status | Show running status, platforms, sessions | | /gateway pair [code] | List pending codes or approve one | | /gateway allow [platform] [userId] | List allowlist or add a user | | /gateway revoke <platform> <userId> | Remove a user from the DB allowlist | | /gateway sessions | List active chat sessions | | /gateway tasks | List background tasks | | /gateway config | Show current configuration | | /gateway admin list | List admin users (DB + config) | | /gateway admin add <p\|*> <uid> | Grant admin privileges | | /gateway admin remove <p\|*> <uid> | Revoke admin | | /gateway admin list | List admin users | | /gateway admin add <p\|*> <uid> | Grant admin privileges | | /gateway admin remove <p\|*> <uid> | Revoke admin | | /gateway tool-policy list | List explicit tool policies | | /gateway tool-policy defaults | Show default policy baseline | | /gateway tool-policy set <p> <u> <t> allow\|deny | Add/update a tool policy | | /gateway tool-policy remove <id> | Delete a policy | | /gateway tool-policy reset | Clear all, back to defaults |

HTTP API

Available when the gateway is running:

| Endpoint | Method | Description | |----------|--------|-------------| | /api/status | GET | Gateway status (running, adapters, clients, sessions) | | /api/sessions | GET | Active sessions | | /api/background | GET | Background tasks | | /api/allowlist | GET | Allowlisted users | | /api/pairing | GET | Pending pairing codes |

Authenticate with Authorization: Bearer <token> if tokens are configured.

WebSocket API

Connect to ws://localhost:3847. Messages are JSON:

// Send a prompt
{ "type": "prompt", "data": { "message": "Hello" } }

// Start a background task
{ "type": "background", "data": { "sessionId": "...", "command": "..." } }

// Ping
{ "type": "ping" }

Receive responses, background task updates, and agent events as server-pushed messages.

Registered Tools

The extension registers these tools for use in pi sessions:

• gateway_status — Check if gateway is running and which adapters are active
• gateway_sessions — List active chat sessions
• gateway_background_tasks — List and manage background tasks
• gateway_pairing — Generate or approve pairing codes
• gateway_tool_policy — Manage tool access policies for external users

Sessions

Each chat gets an isolated session with configurable reset policies:

• daily — Session resets at a specific hour each day (default: 4 AM)
• idle — Session resets after N minutes of inactivity
• both — Whichever triggers first

Sessions persist across gateway restarts in ~/.pi/gateway/gateway-sessions.db.

Background Tasks

Long-running work is spawned in isolated background sessions. Results are delivered back to the parent chat when complete. Managed via /gateway tasks.

Architecture

┌─────────────┐     ┌─────────────────────────────┐
│  pi agent   │◄───►│        pi-gateway           │
│  (RPC)      │     │                             │
└─────────────┘     │  ┌─────────────────────┐    │
                    │  │ Platform Adapters    │    │
┌─────────────┐     │  │ Discord · Telegram   │    │
│ HTTP / WS   │────►│  │ Slack · Twitch       │    │
│ Clients     │     │  │ WhatsApp · WebSocket │    │
└─────────────┘     │  └─────────────────────┘    │
                    │                             │
                    │  ┌─────────────────────┐    │
                    │  │ Sessions Store      │    │
                    │  │ Background Manager  │    │
                    │  │ Security Layer      │    │
                    │  └─────────────────────┘    │
                    └─────────────────────────────┘

• Platform adapters translate incoming platform messages into a unified format
• Sessions store (SQLite) persists per-chat state with reset policies
• Background manager spawns async child processes, delivers results via chat
• Security layer checks allowlists, manages pairing codes, and enforces rate limits

License

MIT