> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Windows Deployment

> Complete guide for deploying PraisonAI Gateway on Windows with multi-channel bots

Deploy the PraisonAI Gateway on Windows with multiple Telegram bots, proper encoding, and production-ready configuration.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Windows Environment Setup"
        subgraph "Step 1: Dependencies"
            PY[🐍 Python 3.9+]
            PKG[📦 praisonai[bot,api]]
            ENV[🔧 UTF-8 Environment]
        end
        
        subgraph "Step 2: Configuration"
            YML[📄 gateway.yaml]
            ENVF[🔐 .env file]
            TOK[🔑 Bot Tokens]
        end
        
        subgraph "Step 3: Deployment"
            GW[🌐 Gateway Process]
            HEALTH[💚 Health Check]
            LOGS[📋 Monitoring]
        end
    end
    
    PY --> PKG
    PKG --> ENV
    ENV --> YML
    YML --> ENVF
    ENVF --> TOK
    TOK --> GW
    GW --> HEALTH
    HEALTH --> LOGS
    
    classDef setup fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef config fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef deploy fill:#10B981,stroke:#7C90A0,color:#fff
    
    class PY,PKG,ENV setup
    class YML,ENVF,TOK config
    class GW,HEALTH,LOGS deploy
```

## Quick Start

<Steps>
  <Step title="Install Dependencies">
    Install Python dependencies with both extras required for gateway:

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install "praisonai[bot,api]"
    ```

    **Why both extras are needed:**

    | Extra   | Provides                                    | Required For                  |
    | ------- | ------------------------------------------- | ----------------------------- |
    | `[bot]` | python-telegram-bot, discord.py, slack SDKs | Platform integrations         |
    | `[api]` | uvicorn, fastapi, starlette                 | Gateway HTTP/WebSocket server |
    | `[all]` | Both + search tools + storage backends      | Complete installation         |

    **Without `[api]` you'll get:**

    ```
    ImportError: Gateway requires starlette and uvicorn.
    Install with: pip install praisonai[api]
    ```
  </Step>

  <Step title="Configure Windows UTF-8">
    **Mandatory for Windows gateway deployments:**

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    $env:PYTHONUTF8 = "1"
    # Alternative:
    $env:PYTHONIOENCODING = "utf-8"
    ```

    **Why this is required:**

    Without UTF-8 configuration, you'll see encoding errors:

    ```
    Error: 'charmap' codec can't encode character '\u26a0' in position 1: character maps to <undefined>
    ```

    This often appears after API failures (OpenAI 429 quota exceeded). Fix billing first, then encoding.
  </Step>

  <Step title="Create Gateway Configuration">
    Create `gateway.yaml`:

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    gateway:
      host: "127.0.0.1"
      port: 8765

    agents:
      assistant:
        model: gpt-4o-mini
        instructions: "You are a helpful AI assistant."
        tools: [search_knowledge]

    channels:
      telegram:
        platform: telegram
        token: ${TELEGRAM_BOT_TOKEN}
        routes:
          default: assistant
    ```

    Create `.env` file:

    ```env theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    TELEGRAM_BOT_TOKEN=your_bot_token_here
    OPENAI_API_KEY=your_openai_key_here
    GATEWAY_AUTH_TOKEN=optional_auth_token
    PYTHONUTF8=1
    ```
  </Step>

  <Step title="Start Gateway">
    Launch the gateway with configuration:

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway start --config gateway.yaml
    ```

    **Expected output:**

    ```
    Gateway starting (host=127.0.0.1 port=8765 config=gateway.yaml agents=-)
    Loading gateway config from gateway.yaml
    Starting gateway on ws://127.0.0.1:8765
    Press Ctrl+C to stop
    ```
  </Step>
</Steps>

***

## Windows-Specific Configuration

### Environment Variables

Windows PowerShell environment setup:

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Session variables (temporary)
$env:TELEGRAM_BOT_TOKEN = "123456:ABC-DEF1234"
$env:OPENAI_API_KEY = "sk-..."
$env:PYTHONUTF8 = "1"

# Persistent variables (permanent)
[Environment]::SetEnvironmentVariable("PYTHONUTF8", "1", "User")
[Environment]::SetEnvironmentVariable("TELEGRAM_BOT_TOKEN", "123456:ABC-DEF1234", "User")
```

### UTF-8 Encoding Setup

**Three ways to configure UTF-8 on Windows:**

<Tabs>
  <Tab title="Environment Variable">
    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    $env:PYTHONUTF8 = "1"
    ```

    Recommended approach - works for current session.
  </Tab>

  <Tab title="System Environment">
    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    [Environment]::SetEnvironmentVariable("PYTHONUTF8", "1", "Machine")
    ```

    System-wide setting - requires admin privileges.
  </Tab>

  <Tab title="Per-Process">
    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    $env:PYTHONIOENCODING = "utf-8"
    ```

    Alternative encoding setting.
  </Tab>
</Tabs>

### Windows Service Installation

For production deployment as Windows service:

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Install NSSM (Non-Sucking Service Manager)
choco install nssm

# Create service
nssm install PraisonAIGateway "C:\Python\python.exe"
nssm set PraisonAIGateway Arguments "-m praisonai gateway start --config C:\PraisonAI\gateway.yaml"
nssm set PraisonAIGateway AppDirectory "C:\PraisonAI"
nssm set PraisonAIGateway AppEnvironmentExtra "PYTHONUTF8=1"

# Start service
sc start PraisonAIGateway
```

***

## Multi-Channel Windows Setup

### Hermes-Style Workforce Example

Complete `gateway.yaml` for 3-bot Hermes workforce:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
gateway:
  host: "127.0.0.1"
  port: 8765

agents:
  cfo:
    model: gpt-4o-mini
    instructions: "You are a CFO assistant. Help with financial analysis and reporting."
    tools: [search_knowledge]
  ops:
    model: gpt-4o-mini  
    instructions: "You are an operations assistant. Help with process optimization."
    tools: [search_knowledge]
  content:
    model: gpt-4o-mini
    instructions: "You are a content assistant. Help with writing and marketing."
    tools: [search_knowledge]

channels:
  telegram_cfo:
    platform: telegram
    token: ${TELEGRAM_CFO_TOKEN}
    routes:
      default: cfo
  telegram_ops:
    platform: telegram
    token: ${TELEGRAM_OPS_TOKEN}
    routes:
      default: ops  
  telegram_content:
    platform: telegram
    token: ${TELEGRAM_CONTENT_TOKEN}
    routes:
      default: content
```

Matching `.env` file:

```env theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Bot tokens - create 3 separate bots in @BotFather
TELEGRAM_CFO_TOKEN=123456:ABC-DEF1234ghIkl-CFO
TELEGRAM_OPS_TOKEN=789012:XYZ-GHI5678jklMn-OPS  
TELEGRAM_CONTENT_TOKEN=345678:PQR-STU9012opqRs-CONTENT

# API keys
OPENAI_API_KEY=sk-your-openai-api-key
GATEWAY_AUTH_TOKEN=your-optional-auth-token

# Windows UTF-8 setup
PYTHONUTF8=1
PYTHONIOENCODING=utf-8
```

### Creating Multiple Telegram Bots

**Important:** Each channel needs its own Telegram bot token.

1. **Create CFO Bot:**
   * Message [@BotFather](https://t.me/botfather)
   * `/newbot`
   * Name: "CFO Assistant Bot"
   * Username: "your\_company\_cfo\_bot"
   * Save token as `TELEGRAM_CFO_TOKEN`

2. **Create Ops Bot:**
   * `/newbot` (same BotFather)
   * Name: "Operations Assistant Bot"
   * Username: "your\_company\_ops\_bot"
   * Save token as `TELEGRAM_OPS_TOKEN`

3. **Create Content Bot:**
   * `/newbot` (same BotFather)
   * Name: "Content Assistant Bot"
   * Username: "your\_company\_content\_bot"
   * Save token as `TELEGRAM_CONTENT_TOKEN`

**Never reuse tokens** - each bot must be separate.

***

## Health Monitoring

### Health Check Commands

Monitor gateway status:

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# PowerShell health check
Invoke-RestMethod -Uri "http://127.0.0.1:8765/health"

# Using curl (if installed)
curl http://127.0.0.1:8765/health

# Using Python
python -c "import urllib.request, json; print(json.loads(urllib.request.urlopen('http://127.0.0.1:8765/health').read()))"
```

**Expected healthy response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "status": "healthy",
  "uptime": 3600.5,
  "agents": 3,
  "sessions": 12,
  "clients": 8,
  "channels": {
    "telegram_cfo": { "platform": "telegram", "running": true },
    "telegram_ops": { "platform": "telegram", "running": true },
    "telegram_content": { "platform": "telegram", "running": true }
  }
}
```

### Process Management

Check running gateway processes:

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Find gateway processes
Get-Process | Where-Object {$_.ProcessName -match "python" -and $_.MainWindowTitle -match "gateway"}

# Alternative: check port usage
netstat -ano | findstr ":8765"

# Kill gateway processes if needed
taskkill /F /IM python.exe /FI "WINDOWTITLE eq *gateway*"
```

***

## Security Configuration

### User Access Control

Configure allowed users to prevent unauthorized access:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# In gateway.yaml
channels:
  telegram_cfo:
    platform: telegram
    token: ${TELEGRAM_CFO_TOKEN}
    allowed_users: ${TELEGRAM_ALLOWED_USERS}
    routes:
      default: cfo
```

`.env` configuration:

```env theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
TELEGRAM_ALLOWED_USERS=123456789,987654321,555666777
```

**Security caveat:** Current gateway Telegram polling path may not enforce allowlist until PraisonAI security fix ships. Verify access control after update.

### Token Security

Secure token storage on Windows:

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Use Windows Credential Manager (recommended)
cmdkey /add:TELEGRAM_BOT_TOKEN /user:praisonai /pass:"123456:ABC-DEF"

# Retrieve token in script
$token = cmdkey /list:TELEGRAM_BOT_TOKEN

# Encrypted environment file
# Use tools like sops or age for production
```

***

## Troubleshooting Windows Issues

### Common Windows Errors

<AccordionGroup>
  <Accordion title="charmap codec error">
    **Symptoms:**

    ```
    Error: 'charmap' codec can't encode character '\u26a0' in position 1: character maps to <undefined>
    ```

    **Causes:**

    1. Missing UTF-8 environment configuration
    2. OpenAI API failure (429 quota) + encoding issue

    **Solutions:**

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Set UTF-8 environment
    $env:PYTHONUTF8 = "1"

    # Check OpenAI billing
    # Visit platform.openai.com/billing

    # Restart gateway after both fixes
    ```
  </Accordion>

  <Accordion title="ImportError: Gateway requires starlette">
    **Error:**

    ```
    ImportError: Gateway requires starlette and uvicorn.
    Install with: pip install praisonai[api]
    ```

    **Solution:**

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip uninstall praisonai
    pip install "praisonai[bot,api]"
    ```
  </Accordion>

  <Accordion title="Bot stops responding (409 Conflict)">
    **Symptoms:**

    * Bot works initially, then stops mid-session
    * Log shows: `Conflict: terminated by other getUpdates request`
    * Health check still shows `"running": true`

    **Cause:** Duplicate gateway processes polling same token

    **Solution:**

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Stop all gateway processes
    Get-Process | Where-Object {$_.ProcessName -match "python"} | Stop-Process -Force

    # Verify port is free
    netstat -ano | findstr ":8765"

    # Start single gateway instance
    praisonai gateway start --config gateway.yaml
    ```
  </Accordion>

  <Accordion title="25-30 second response delay">
    **Symptoms:**

    * Telegram typing indicator disappears after 5 seconds
    * Reply comes 20-30 seconds later
    * No error messages

    **Explanation:** This is **normal behavior** for RAG + LLM processing.

    **User guidelines:**

    * Do not send duplicate messages during wait
    * Do not restart gateway during response window
    * Typing indicator renewal fix is pending in PraisonAI
  </Accordion>
</AccordionGroup>

### Windows-Specific Debugging

Enable detailed logging:

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Set debug environment
$env:PRAISONAI_LOG_LEVEL = "DEBUG"

# Start with verbose output
praisonai gateway start --config gateway.yaml --verbose

# View logs
Get-Content ~/.praisonai/logs/gateway.log -Tail 50 -Wait
```

Check Windows firewall:

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Allow Python through firewall
New-NetFirewallRule -DisplayName "PraisonAI Gateway" -Direction Inbound -Protocol TCP -LocalPort 8765 -Action Allow

# Test connectivity
Test-NetConnection -ComputerName 127.0.0.1 -Port 8765
```

***

## Performance Optimization

### Windows Resource Configuration

Optimize for Windows deployment:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# gateway.yaml - Windows optimizations
gateway:
  host: "127.0.0.1"
  port: 8765
  max_connections: 50        # Lower for Windows
  worker_processes: 1        # Single process on Windows
  keep_alive_timeout: 30
  client_timeout: 120
  
# Environment variables for performance
UVICORN_WORKERS=1
UVICORN_KEEP_ALIVE=30
PRAISONAI_CACHE_SIZE=1000
```

PowerShell performance script:

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Optimize Python process priority
$proc = Get-Process | Where-Object {$_.ProcessName -eq "python" -and $_.MainWindowTitle -match "gateway"}
$proc.PriorityClass = "High"

# Set power plan to high performance
powercfg /setactive 8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c
```

***

## Production Deployment

### Windows Server Configuration

For production Windows Server deployment:

```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Install as Windows Service
sc create "PraisonAI Gateway" binPath="C:\Python\python.exe -m praisonai gateway start --config C:\PraisonAI\gateway.yaml"
sc config "PraisonAI Gateway" start=auto
sc description "PraisonAI Gateway" "PraisonAI Multi-Channel Bot Gateway"

# Configure service recovery
sc failure "PraisonAI Gateway" reset=86400 actions=restart/30000/restart/60000/restart/60000

# Start service
sc start "PraisonAI Gateway"
```

IIS reverse proxy (optional):

```xml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
<!-- web.config for IIS reverse proxy -->
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Gateway WebSocket" stopProcessing="true">
          <match url="ws" />
          <action type="Rewrite" url="http://127.0.0.1:8765/ws" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use Windows Task Scheduler for monitoring">
    Create monitoring task:

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Create health check script
    @'
    $response = Invoke-RestMethod -Uri "http://127.0.0.1:8765/health" -ErrorAction SilentlyContinue
    if ($response.status -ne "healthy") {
        Restart-Service "PraisonAI Gateway"
        Write-EventLog -LogName Application -Source "PraisonAI" -EventID 1001 -Message "Gateway restarted"
    }
    '@ | Out-File -FilePath C:\PraisonAI\health-check.ps1

    # Schedule every 5 minutes
    schtasks /create /sc minute /mo 5 /tn "PraisonAI Health Check" /tr "powershell.exe C:\PraisonAI\health-check.ps1"
    ```
  </Accordion>

  <Accordion title="Configure Windows Event Logging">
    Enable application logging:

    ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Create event source
    New-EventLog -LogName Application -Source "PraisonAI Gateway"

    # Log gateway events
    Write-EventLog -LogName Application -Source "PraisonAI Gateway" -EventID 1000 -Message "Gateway started successfully"
    ```
  </Accordion>

  <Accordion title="Use Windows Subsystem for Linux (WSL) alternative">
    For development, consider WSL:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # In WSL Ubuntu
    sudo apt update && sudo apt install python3-pip
    pip3 install "praisonai[bot,api]"

    # UTF-8 is default in WSL
    praisonai gateway start --config gateway.yaml
    ```

    This avoids Windows-specific encoding issues during development.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Gateway Overview" icon="broadcast-tower" href="/docs/features/gateway-overview">
    Architecture and concepts
  </Card>

  <Card title="Multi-Channel Telegram" icon="paper-plane" href="/docs/features/gateway-telegram-multichannel">
    Hermes workforce pattern
  </Card>
</CardGroup>