> ## 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.

# Standalone Bot YAML

> Describe a standalone gateway + agent + channels declaratively

Describe your agent, gateway, and channel platforms in a single YAML file — no Python required.

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

agent = Agent(name="bot-agent", instructions="Reply to users across chat channels.")
agent.start("Answer incoming messages from Telegram and Discord.")
```

The user defines a `bot.yaml`; the gateway loads it and connects the agent to every configured channel.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Standalone Bot YAML"
        In[📄 bot.yaml] --> GW[🗼 Gateway]
        GW --> Agent[🤖 Agent]
        Agent --> Out[✅ Channel Reply]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class In input
    class GW process
    class Agent agent
    class Out output
```

## How It Works

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

    User->>Channel: Message on Telegram / Discord
    Channel->>Gateway: Forward inbound event
    Gateway->>Agent: Run configured agent
    Agent-->>User: Reply on the same channel
```

### Config Structure

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "YAML Config"
        Y[📄 bot.yaml] --> A[agent]
        Y --> G[gateway]
        Y --> P[platforms]
    end
    A --> Agent[🤖 Agent]
    G --> GW[🗼 WebSocket\nGateway]
    P --> C1[💬 Telegram]
    P --> C2[🎮 Discord]
    Agent --> GW
    GW --> C1
    GW --> C2

    classDef yaml fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef gateway fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef channel fill:#10B981,stroke:#7C90A0,color:#fff

    class Y,A,G,P yaml
    class Agent agent
    class GW gateway
    class C1,C2 channel
```

## Quick Start

<Steps>
  <Step title="Install">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install praisonaiagents "praisonai-bot[gateway,bot]"
    ```
  </Step>

  <Step title="Set credentials">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export OPENAI_API_KEY=your_openai_api_key
    export TELEGRAM_BOT_TOKEN=your_telegram_token
    ```
  </Step>

  <Step title="Create bot.yaml">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agent:
      name: assistant
      instructions: You are a helpful assistant.
      llm: gpt-4o-mini

    gateway:
      host: 127.0.0.1
      port: 8765

    platforms:
      telegram:
        token: ${TELEGRAM_BOT_TOKEN}
    ```
  </Step>

  <Step title="Start the gateway with your YAML">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-bot gateway start --config bot.yaml
    ```

    The gateway registers the agent and starts all configured channel bots automatically.
  </Step>
</Steps>

***

## Config Options Reference

### `agent` section

| Key                  | Type  | Default         | Description                                                    |
| -------------------- | ----- | --------------- | -------------------------------------------------------------- |
| `agent.name`         | `str` | required        | Agent display name, used as the `agent_id` for gateway routing |
| `agent.instructions` | `str` | required        | System prompt / instructions for the agent                     |
| `agent.llm`          | `str` | `"gpt-4o-mini"` | LLM model identifier (e.g. `gpt-4o`, `gpt-4o-mini`)            |

### `gateway` section

| Key            | Type  | Default       | Description                       |
| -------------- | ----- | ------------- | --------------------------------- |
| `gateway.host` | `str` | `"127.0.0.1"` | Host to bind the WebSocket server |
| `gateway.port` | `int` | `8765`        | Port to listen on                 |

### `platforms` section

Each key under `platforms` is a platform name. Use `${VAR_NAME}` for environment variable interpolation.

| Key pattern              | Type  | Description                                                    |
| ------------------------ | ----- | -------------------------------------------------------------- |
| `platforms.<name>.token` | `str` | Bot token for the platform. Supports `${ENV_VAR}` substitution |

**Supported platforms:** `telegram`, `discord`, `slack`, `whatsapp`, and any platform registered via entry points.

***

## Environment Variable Interpolation

Values in the form `${VAR_NAME}` are resolved from the current environment at startup:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}   # reads os.environ["TELEGRAM_BOT_TOKEN"]
  discord:
    token: ${DISCORD_BOT_TOKEN}    # reads os.environ["DISCORD_BOT_TOKEN"]
```

Tokens stored in `~/.praisonai/.env` (written by `praisonai-bot onboard`) are loaded automatically before interpolation.

***

## When to Pick YAML vs Python

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{Who configures it?} -->|Non-developer / ops| YAML[📄 YAML config]
    Q -->|Developer / code-first| Python[🐍 Python script]

    YAML --> Y1[✅ No code to maintain]
    YAML --> Y2[✅ Easy credential rotation]
    YAML --> Y3[✅ Works with praisonai-bot gateway start]

    Python --> P1[✅ Programmatic agent construction]
    Python --> P2[✅ Dynamic agent_id or custom registration]
    Python --> P3[✅ Custom middleware / hooks]

    classDef yaml fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef python fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef yes fill:#10B981,stroke:#7C90A0,color:#fff

    class Q yaml
    class YAML,Python python
    class Y1,Y2,Y3,P1,P2,P3 yes
```

| Scenario                                     | Use                                                |
| -------------------------------------------- | -------------------------------------------------- |
| Operations team manages tokens               | **YAML** — credentials stay out of code            |
| Static single-agent setup                    | **YAML** — fewer moving parts                      |
| Dynamic agents (created at runtime)          | **Python** — full control over `register_agent()`  |
| Custom gateway middleware or hooks           | **Python** — subclass or extend `WebSocketGateway` |
| Multiple environments (dev / staging / prod) | **YAML** — per-environment files with env vars     |

***

## Common Patterns

### Multi-platform setup

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent:
  name: assistant
  instructions: You are a helpful assistant.
  llm: gpt-4o-mini

gateway:
  host: 0.0.0.0
  port: 8765

platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
  discord:
    token: ${DISCORD_BOT_TOKEN}
  slack:
    token: ${SLACK_BOT_TOKEN}
```

### Custom port from environment

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

Or set the `GATEWAY_PORT` environment variable — the CLI reads it automatically when `--port` is not passed.

***

## Best Practices

<AccordionGroup>
  <Accordion title="Always use ${...} for tokens">
    Never hardcode tokens in YAML. Use environment variables and store them in `~/.praisonai/.env` (written by `praisonai-bot onboard`) or your secrets manager.

    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Good
    platforms:
      telegram:
        token: ${TELEGRAM_BOT_TOKEN}

    # Never do this
    platforms:
      telegram:
        token: 1234567890:ABCdef...
    ```
  </Accordion>

  <Accordion title="Run praisonai-bot gateway doctor before going live">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai-bot gateway doctor --config bot.yaml
    ```

    This validates every channel token before starting, so a bad token fails fast instead of silently reconnecting.
  </Accordion>

  <Accordion title="Use separate YAML files per environment">
    Keep `dev.yaml`, `staging.yaml`, and `prod.yaml` — each referencing different environment variables. Pass the right one with `--config`.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Standalone Bot Gateway (Python)" icon="server" href="/docs/features/standalone-bot-gateway">
    Python API equivalent — register agents programmatically
  </Card>

  <Card title="Gateway CLI" icon="tower-broadcast" href="/docs/features/gateway-cli">
    Full list of gateway CLI commands
  </Card>

  <Card title="BotOS" icon="robot" href="/docs/features/botos">
    Multi-platform bot orchestration
  </Card>

  <Card title="praisonai-bot SDK" icon="comments" href="/docs/sdk/praisonai-bot/index">
    Full bot-tier SDK reference
  </Card>
</CardGroup>