Pi-Gateway

Hermes-style messaging gateway for pi-coding-agent — multi-platform session management, security, and background tasks.

Installation

pi install npm:@0xkobold/pi-gateway

Or as part of the meta-extension:

pi install npm:@0xkobold/pi-kobold

Features

• Per-Chat Sessions — Unique session ID per platform/channel with reset policies
• Reset Policies — Daily (hour-based) and idle (minutes-based) session resets
• Session Persistence — Sessions survive restarts via SQLite (sql.js)
• Background Tasks — Isolated sessions for long-running commands
• Security — Per-platform user allowlists and DM pairing flow
• Rate Limiting — Configurable per-identifier rate limiting
• Multi-Platform Adapters — Discord, Telegram, Slack, WhatsApp, Twitch, WebSocket

Architecture

┌──────────────────────────────────────────────────────┐
│                    Pi-Gateway                         │
├──────────────┬──────────────┬────────────────────────┤
│  Sessions    │  Security    │  Background Tasks      │
│  ──────────  │  ──────────  │  ──────────────────   │
│  • Per-chat  │  • Allowlist │  • Isolated sessions   │
│  • Reset     │  • Pairing   │  • Progress tracking   │
│  • Persist   │  • Rate limit│  • Result delivery     │
├──────────────┴──────────────┴────────────────────────┤
│              Platform Adapters                        │
│  Discord · Telegram · Slack · WhatsApp · Twitch      │
├──────────────────────────────────────────────────────┤
│              SQLite via sql.js                        │
└──────────────────────────────────────────────────────┘

Commands

Command	Description
/gateway start [port]	Start the gateway
/gateway stop	Stop the gateway
/gateway status	Show status
/gateway restart	Restart the gateway
/gateway pair <code>	Approve a pairing code
/gateway allow <platform> <userId>	Add user to allowlist
/gateway sessions	List active sessions
/gateway tasks	List background tasks
/gateway config	Show configuration

Tools

Tool	Description
gateway_status	Check gateway status
gateway_sessions	List active sessions
gateway_background_tasks	List and manage background tasks
gateway_pairing	Generate, list, or approve pairing codes

Programmatic API

Pi-gateway now exports a programmatic API so it can be started from outside a pi session:

import { startGateway, stopGateway, isGatewayRunning, getStatus } from '@0xkobold/pi-gateway/api';

// Check if already running
const running = await isGatewayRunning(3847);

// Start the gateway
const status = await startGateway({ port: 3847, host: '0.0.0.0' });

// Get status
const current = getStatus();

// Stop
await stopGateway();

Function	Description
startGateway(opts?)	Start HTTP/WS server, adapters, and cron
stopGateway()	Stop all adapters, close server, kill RPC process
isGatewayRunning(port?)	Check if a gateway is already running on a port
getStatus()	Get current status (running, adapters, clients, sessions)
getConfig()	Get current gateway config
isRunning()	Check if gateway is running (sync)
getAdapter(platform)	Get a platform adapter by name
getAdapters()	Get all active adapters
sendMessage(platform, channelId, content)	Send a message through a platform adapter
broadcast(event, data)	Broadcast to all connected WebSocket clients

Start Options

interface StartGatewayOptions {
  port?: number;       // Override config port
  host?: string;      // Override config host
  noAgent?: boolean;  // Don't spawn pi RPC process (when pi is already running)
}

Session Reset Policies

• idle — Reset after N minutes of inactivity (default: 1440 = 24h)
• daily — Reset at a specific hour each day (default: 4:00)
• both — Reset on either condition

Security

Allowlist Mode

By default, all users are allowed (allowAll: true). To restrict access:

1. Set allowAll: false in config
2. Use pairing codes or /gateway allow to grant access

Pairing Flow

1. User sends a message on a platform
2. Agent generates a pairing code via gateway_pairing (generate)
3. Admin approves code via /gateway pair <code>
4. User is added to the allowlist

Configuration

Stored at ~/.0xkobold/gateway/config.json:

{
  "port": 3847,
  "host": "localhost",
  "tokens": [],
  "corsOrigins": ["*"],
  "enableWebSocket": true,
  "enableHttp": true,
  "security": {
    "allowAll": true,
    "requirePairing": false
  },
  "sessions": {
    "resetPolicy": "idle",
    "dailyHour": 4,
    "idleMinutes": 1440
  },
  "platforms": {
    "discord": {
      "enabled": false,
      "botToken": ""
    }
  }
}

Local Storage

Data is stored in SQLite via sql.js (WebAssembly) for cross-runtime compatibility (Node.js and Bun):

• ~/.0xkobold/gateway-sessions.db — Session data
• ~/.0xkobold/gateway-security.db — Allowlist, pairing codes, rate limits
• ~/.0xkobold/gateway-background-tasks.db — Background task records

Local Development

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

License

MIT