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

# Gateway CLI

> Command-line interface for managing the PraisonAI Gateway daemon and server

<Note>
  The gateway now ships in the `praisonai-bot` package. `praisonai serve gateway` still works exactly as documented here; for a standalone install see [praisonai-bot Migration](/docs/guides/praisonai-bot-migration).
</Note>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="gateway-cli-agent", instructions="Manage gateway via CLI commands.")
agent.start("Start the gateway and show its status.")
```

Gateway CLI provides commands for starting, monitoring, and managing the PraisonAI Gateway server and its daemon service, including channel supervision controls for resilient bot management.

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# gateway.yaml
agents:
  assistant:
    instructions: "You are a helpful AI assistant."
    model: gpt-4o-mini

channels:
  telegram:
    token: "${TELEGRAM_BOT_TOKEN}"
    platform: telegram
```

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

<Note>
  This page documents the **WebSocket multi-agent Gateway daemon**. The canonical CLI command is `praisonai-bot gateway start` (bot-tier package). When the `praisonai` wrapper is co-installed, `praisonai gateway start` works as a convenience alias.

  For the **UI-Gateway** (Pattern C integration), see [`praisonai serve ui-gateway`](/docs/cli/serve#ui-gateway-server-options).

  For detailed information about channel resilience and operator controls, see [Channel Supervision](/docs/features/gateway-channel-supervision).
</Note>

The user runs `praisonai gateway start`; the CLI launches the daemon, supervises channels, and keeps the WebSocket gateway reachable.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Gateway CLI Flow"
        User[👤 User] --> CLI[💻 CLI]
        CLI --> Daemon[⚙️ Daemon]
        Daemon --> Gateway[🗼 Gateway]
        Gateway --> Health[🏥 Health Check]
    end
    
    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef config fill:#6366F1,stroke:#7C90A0,color:#fff
    
    class User user
    class CLI,Daemon tool
    class Gateway,Health success
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Gateway CLI

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result    Agent-->>User: Response
```

## Quick Start

<Note>
  The gateway runs in the **foreground**. The daemon is installed by `praisonai-bot gateway install` (or automatically by `praisonai-bot onboard`).
</Note>

<Steps>
  <Step title="Start Gateway">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Canonical (bot-tier, no wrapper required)
    praisonai-bot gateway start

    # Wrapper alias (requires pip install praisonai)
    praisonai gateway start
    ```

    <Tip>Only one gateway can run per host:port. Stop the existing one with `praisonai-bot gateway stop` first, or use a different port.</Tip>
  </Step>

  <Step title="Check Status">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway status
    ```
  </Step>

  <Step title="Test Health Endpoint">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    curl http://127.0.0.1:8765/health
    ```
  </Step>
</Steps>

***

## Commands

### Gateway Management

| Command                      | Description                                             | Example                                          |
| ---------------------------- | ------------------------------------------------------- | ------------------------------------------------ |
| `praisonai gateway start`    | Start the gateway server (foreground)                   | `praisonai gateway start --port 9000`            |
| `praisonai gateway stop`     | Stop a running gateway instance                         | `praisonai gateway stop --force`                 |
| `praisonai gateway status`   | Check gateway and daemon status                         | `praisonai gateway status --daemon-only`         |
| `praisonai gateway doctor`   | Validate channel credentials before start (pre-flight)  | `praisonai gateway doctor --config gateway.yaml` |
| `praisonai gateway channels` | List configured channels (add `--probe` to check creds) | `praisonai gateway channels --probe`             |

### Daemon Service

| Command                       | Description           | Example                                |
| ----------------------------- | --------------------- | -------------------------------------- |
| `praisonai gateway install`   | Install as OS daemon  | `praisonai gateway install --no-start` |
| `praisonai gateway uninstall` | Remove daemon service | `praisonai gateway uninstall`          |
| `praisonai gateway logs`      | Show daemon logs      | `praisonai gateway logs -n 100`        |
| `praisonai gateway restart`   | Restart the daemon    | See restart commands below             |

### Channel Control

| Command                       | Description               | Example                                |
| ----------------------------- | ------------------------- | -------------------------------------- |
| `praisonai gateway pause`     | Pause a channel           | `praisonai gateway pause telegram`     |
| `praisonai gateway resume`    | Resume a paused channel   | `praisonai gateway resume telegram`    |
| `praisonai gateway reconnect` | Force reconnect a channel | `praisonai gateway reconnect telegram` |

### Inbound Hooks

| Command                                 | Description                         | Example                                               |
| --------------------------------------- | ----------------------------------- | ----------------------------------------------------- |
| `praisonai gateway hooks add <path>`    | Register an inbound webhook trigger | `praisonai gateway hooks add gmail --agent assistant` |
| `praisonai gateway hooks list`          | List registered hooks               | `praisonai gateway hooks list`                        |
| `praisonai gateway hooks remove <path>` | Remove an inbound hook              | `praisonai gateway hooks remove gmail`                |

See [Gateway Inbound Hooks](/docs/features/gateway-inbound-hooks) for full details.

### Testing & Debugging

| Command                  | Description       | Example                                                                  |
| ------------------------ | ----------------- | ------------------------------------------------------------------------ |
| `praisonai gateway send` | Send test message | `praisonai gateway send --channel telegram --channel-id 12345 -m "test"` |

***

## Command Reference

<Tabs>
  <Tab title="start">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway start [OPTIONS]

    Options:
      --host TEXT                     Host to bind to [default: 127.0.0.1]
      --port INTEGER                  Port to listen on [default: 8765 or $GATEWAY_PORT]
      --agents TEXT                   Path to agent configuration file
      --config TEXT                   Path to gateway.yaml for multi-bot mode
      --reliability [production|default|off]
                                      Reliability preset — composes drain + admission.
                                      production (15s drain + CPU-scaled admission),
                                      default (5s drain, no admission), off (immediate teardown).
                                      Overrides `reliability:` from YAML but is overridden
                                      by explicit --drain-timeout / --max-concurrent-runs.
      --preflight / --no-preflight    Validate channel credentials before
                                      starting (fail fast on bad tokens)
                                      [default: --preflight]

    Examples:
      praisonai gateway start
      praisonai gateway start --config gateway.yaml
      praisonai gateway start --agents agents.yaml --port 9000
      praisonai gateway start --config gateway.yaml --no-preflight
      praisonai gateway start --config gateway.yaml --reliability production
      GATEWAY_PORT=9000 praisonai gateway start
    ```

    <Note>
      `--reliability` overrides the `reliability:` / `gateway.reliability:` key in YAML. See [Gateway Reliability Presets](/docs/features/gateway-reliability) for profile details and precedence rules.
    </Note>
  </Tab>

  <Tab title="stop">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway stop [OPTIONS]

    Options:
      --host TEXT         Gateway host [default: 127.0.0.1]
      --port INTEGER      Gateway port [default: 8765 or $GATEWAY_PORT]
      --force             Force stop (kill process)

    Examples:
      praisonai gateway stop
      praisonai gateway stop --port 9000
      praisonai gateway stop --force
    ```

    <Note>
      `praisonai gateway stop` performs a graceful drain — it waits up to **10 seconds** for in-flight agent turns and queued messages before closing. Use `--force` to skip the drain and terminate immediately.
    </Note>
  </Tab>

  <Tab title="status">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway status [OPTIONS]

    Options:
      --host TEXT         Gateway host [default: 127.0.0.1]
      --port INTEGER      Gateway port [default: 8765 or $GATEWAY_PORT]
      --daemon-only       Show only daemon status

    Examples:
      praisonai gateway status
      praisonai gateway status --port 9000
      praisonai gateway status --daemon-only
    ```
  </Tab>

  <Tab title="doctor">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway doctor [OPTIONS]

    Options:
      -c, --config TEXT   Path to gateway.yaml [default: gateway.yaml]
      --json              Output JSON

    Examples:
      praisonai gateway doctor
      praisonai gateway doctor --config my-gateway.yaml --json
    ```
  </Tab>

  <Tab title="channels">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway channels [OPTIONS]

    Options:
      -c, --config TEXT   Path to gateway.yaml [default: gateway.yaml]
      --json              Output JSON format
      --probe             Probe each channel's credentials

    Examples:
      praisonai gateway channels
      praisonai gateway channels --config my-gateway.yaml --json
      praisonai gateway channels --probe
    ```
  </Tab>

  <Tab title="pause">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway pause <channel-name> [OPTIONS]

    Options:
      --url TEXT    Gateway WebSocket URL [default: ws://127.0.0.1:8765]

    Examples:
      praisonai gateway pause telegram
      praisonai gateway pause discord --url ws://localhost:8000
    ```
  </Tab>

  <Tab title="resume">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway resume <channel-name> [OPTIONS]

    Options:
      --url TEXT    Gateway WebSocket URL [default: ws://127.0.0.1:8765]

    Examples:
      praisonai gateway resume telegram
      praisonai gateway resume discord --url ws://localhost:8000
    ```
  </Tab>

  <Tab title="reconnect">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai gateway reconnect <channel-name> [OPTIONS]

    Options:
      --url TEXT    Gateway WebSocket URL [default: ws://127.0.0.1:8765]

    Examples:
      praisonai gateway reconnect telegram
      praisonai gateway reconnect discord --url ws://localhost:8000
    ```
  </Tab>
</Tabs>

***

## Pre-flight credential check

`praisonai gateway doctor` validates every channel's token **before** the gateway starts, so a bad or expired credential fails fast with a precise per-channel reason instead of disappearing into the supervisor's silent reconnect loop.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Pre-flight credential check"
        Cfg[📄 gateway.yaml] --> Probe[🔍 probe_all]
        Probe --> Tel[✓ Telegram getMe]
        Probe --> Sl[✗ Slack auth.test]
        Probe --> Dis[✓ Discord identify]
        Tel --> Verdict[📋 Per-channel verdict]
        Sl --> Verdict
        Dis --> Verdict
        Verdict --> Exit{All OK?}
        Exit -->|Yes| Start[🚀 gateway start]
        Exit -->|No| Fail[❌ exit 1 — fix tokens]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff
    classDef bad fill:#8B0000,stroke:#7C90A0,color:#fff

    class Cfg input
    class Probe,Verdict process
    class Tel,Dis,Start ok
    class Sl,Fail bad
```

### Examples

Quick health check:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai gateway doctor
telegram     ✓  @my_support_bot
slack        ✗  invalid_auth (token expired)
discord      ✓  @MySupport
```

CI-friendly JSON:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai gateway doctor --json
{
  "telegram": {"ok": true,  "platform": "telegram", "bot_username": "my_support_bot"},
  "slack":    {"ok": false, "platform": "slack",    "error": "invalid_auth"},
  "discord":  {"ok": true,  "platform": "discord",  "bot_username": "MySupport"}
}
```

Same verdict via the listing command:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai gateway channels --probe
```

### Pre-flight gate on start

`praisonai gateway start` runs the same probe automatically before launch when invoked with `--config gateway.yaml`:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai gateway start --config gateway.yaml
slack        ✗  invalid_auth (token expired)

Pre-flight check failed — aborting start. Fix the channel credentials
above or pass --no-preflight to skip.
```

To bypass during local dev (e.g. flaky probe network):

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

### Token resolution

The probe loads `~/.praisonai/.env` first, so `${VAR}` placeholders set by `praisonai onboard` resolve exactly like they do at runtime — `doctor`, `channels --probe`, and `start --preflight` all share the same token-resolution path.

### Per-channel timeout

Each probe is bounded by a 15-second deadline; a stuck adapter is reported as `"probe timed out after 15s"` and does not hang the aggregate.

### Exit codes

| Outcome                                      | Exit code |
| -------------------------------------------- | --------- |
| All channels probe OK                        | `0`       |
| Any channel fails                            | `1`       |
| `gateway doctor` with no channels configured | `0`       |

### When to use which

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q[Need to check credentials?] -->|Just-in-time health check| Doctor[praisonai gateway doctor]
    Q -->|Already using channels list?| WithList[praisonai gateway channels --probe]
    Q -->|About to start the gateway?| Auto[Default --preflight runs the same check]
    Q -->|Programmatic healthcheck endpoint| Python[BotOS.probe_all]

    classDef pick fill:#10B981,stroke:#7C90A0,color:#fff
    classDef alt fill:#6366F1,stroke:#7C90A0,color:#fff
    class Doctor pick
    class WithList,Auto,Python alt
```

<AccordionGroup>
  <Accordion title="Programmatic check (Python)">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import asyncio
    from praisonai.bots import Bot, BotOS

    botos = BotOS(
        bots=[
            Bot("telegram", token="..."),
            Bot("slack",    token="..."),
        ],
        enable_supervision=False,
    )

    results = asyncio.run(botos.probe_all(timeout=15.0))
    for platform, r in results.items():
        print(platform, "ok" if r.ok else r.error)
    ```
  </Accordion>
</AccordionGroup>

***

## Environment Variables

| Variable       | Description                                          | Default |
| -------------- | ---------------------------------------------------- | ------- |
| `GATEWAY_PORT` | Port for start/stop/status when --port is not passed | `8765`  |

<Note>
  The `GATEWAY_PORT` environment variable is used by `start`, `stop`, and `status` commands when the `--port` option is not explicitly provided. Invalid values silently fall back to `8765`.
</Note>

***

## Single-Instance Enforcement

PraisonAI enforces a single gateway instance per host:port combination using PID locks.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start[🚀 Gateway Start] --> PortCheck{🔍 Port Available?}
    PortCheck -->|Yes| PIDLock{🔒 PID Lock?}
    PortCheck -->|No| Error1[❌ Port Error]
    PIDLock -->|Acquired| Success[✅ Start Gateway]
    PIDLock -->|Conflict| Error2[❌ Instance Error]
    Error1 --> Stop1[💡 Use Different Port]
    Error2 --> Stop2[💡 Stop Existing Gateway]
    
    classDef start fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef error fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef solution fill:#189AB4,stroke:#7C90A0,color:#fff
    
    class Start start
    class PortCheck,PIDLock check
    class Success success
    class Error1,Error2 error
    class Stop1,Stop2 solution
```

**Lock File Location:** `~/.praisonai/gateway-<safe_host>-<port>.pid`

The `safe_host` replaces `:` and `.` with `_` (so `127.0.0.1` becomes `127_0_0_1`). Each host:port combination gets its own lock file, allowing multiple gateways on different ports.

***

## Restart the Daemon

Use these OS-specific commands to restart the daemon service (same commands shown in the onboard Done panel):

<Tabs>
  <Tab title="macOS">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    launchctl kickstart -k gui/$(id -u)/ai.praison.bot
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    systemctl --user restart praisonai-bot
    ```
  </Tab>

  <Tab title="Windows">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway
    ```
  </Tab>
</Tabs>

***

## Status Output Examples

### Healthy Gateway

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai gateway status
Gateway PID lock: Process 12345 running (127.0.0.1:8765)
Port 127.0.0.1:8765: In use
Daemon service: Running (launchd)
Process ID: 12345
Gateway server: Reachable at http://127.0.0.1:8765/health
  Status: healthy
  Uptime: 3600.5 seconds
  Agents: 2
  Sessions: 1
  Clients: 3
  Channels: 2 configured
```

### Daemon Issues

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai gateway status
Daemon service: Installed but not running (launchd)
Gateway not reachable at http://127.0.0.1:8765/health
```

### Not Installed

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
$ praisonai gateway status --daemon-only
Daemon service: Not installed (systemd)
```

***

## Platform Support

Gateway CLI works across platforms with native daemon integration:

| Platform    | Service Type                           | Log Location                         | Management                                                                 |
| ----------- | -------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------- |
| **macOS**   | LaunchAgent (`ai.praison.bot`)         | `~/.praisonai/logs/bot-stderr.log`   | `launchctl kickstart -k gui/$(id -u)/ai.praison.bot`                       |
| **Linux**   | systemd user service (`praisonai-bot`) | `journalctl --user -u praisonai-bot` | `systemctl --user restart praisonai-bot`                                   |
| **Windows** | Scheduled Task (`PraisonAIGateway`)    | Windows Event Log                    | `schtasks /End /TN PraisonAIGateway && schtasks /Run /TN PraisonAIGateway` |

***

## Configuration Files

<Tabs>
  <Tab title="agents.yaml">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Simple agent configuration
    agent:
      name: "support"
      instructions: "You are a helpful support agent"
      model: "gpt-4o-mini"
      tools:
        - search_web
      memory: true
    ```
  </Tab>

  <Tab title="gateway.yaml">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Multi-bot configuration
    agents:
      support:
        instructions: "You are a support agent"
        model: "gpt-4o-mini"
      sales:
        instructions: "You are a sales agent"
        model: "claude-3-5-sonnet-20241022"

    channels:
      telegram:
        token: "${TELEGRAM_BOT_TOKEN}"
        routing:
          default: support
      discord:
        token: "${DISCORD_BOT_TOKEN}"
        routing:
          default: sales
    ```
  </Tab>
</Tabs>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use daemon-only for health checks">
    Use `--daemon-only` flag when monitoring daemon status in scripts or CI/CD pipelines to avoid gateway connection attempts.
  </Accordion>

  <Accordion title="Check logs for troubleshooting">
    Always check `praisonai gateway logs` when the daemon is running but gateway is unreachable - this reveals startup errors.
  </Accordion>

  <Accordion title="Test channel configuration">
    Use `praisonai gateway send` to test channel bot configuration before deploying to production environments.
  </Accordion>

  <Accordion title="Monitor daemon status regularly">
    Set up monitoring that runs `praisonai gateway status --daemon-only` to detect service failures quickly.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Gateway Server" icon="tower-broadcast" href="/docs/features/gateway">
    Gateway architecture and configuration
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/docs/guides/troubleshoot-gateway">
    Common gateway issues and solutions
  </Card>
</CardGroup>