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

# Zero-Config Gateway

> Bring a bot up with just an env var — no channels: block required

Set your bot's token, run `praisonai gateway` — you have a working bot. No YAML required.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# One agent, one env var, one command — a live Telegram bot.
from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant."
)
# Then in a shell:
#   export TELEGRAM_BOT_TOKEN=123:abc
#   praisonai gateway
```

The gateway detects any platform whose credential env var(s) are all present and registers a channel for it — so a single token brings a bot up with zero `channels:` config.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Zero-Config Bring-up"
        Env[🔑 TELEGRAM_BOT_TOKEN=...] --> GW[🌐 praisonai gateway]
        GW --> Detect[🔍 Detect credential]
        Detect --> Register[⚙️ Register channel]
        Register --> Live[✅ Live Telegram bot]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Env input
    class GW,Detect,Register process
    class Live result
```

## Quick Start

**1. One platform, one line**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export TELEGRAM_BOT_TOKEN=123:abc
praisonai gateway
```

One log line confirms the bot is live:

```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Auto-enabled channel 'telegram' from TELEGRAM_BOT_TOKEN
```

**2. Multiple platforms fan out automatically**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export TELEGRAM_BOT_TOKEN=...
export DISCORD_BOT_TOKEN=...
export SLACK_BOT_TOKEN=...
export SLACK_APP_TOKEN=...
praisonai gateway
```

All three come up — still no `channels:` block.

**3. Add YAML only when you want to customise**

Explicit `channels:` entries always win. Add YAML the moment you need routes, per-channel policy, or a non-env token; leave everything else to the env var.

***

## How It Works

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

    User->>Shell: export TELEGRAM_BOT_TOKEN=...
    User->>Shell: praisonai gateway
    Shell->>Gateway: start
    Gateway->>Registry: list_platforms()
    Registry-->>Gateway: telegram, discord, slack, whatsapp, ...
    Gateway->>Gateway: for each platform, is every credential env var set?
    Gateway->>Channel: register 'telegram' with default routes → assistant
    Channel-->>User: bot is live
```

Auto-enabled channels get `routes: {dm: <agent>, group: <agent>, default: <agent>}`. The `<agent>` resolves in this order:

1. `routing.default` (if set)
2. First key in `agents:` (if any)
3. Single-bot `agent.name` (if set)
4. Literal `"assistant"` (final fallback)

***

## Which env vars trigger which channel

A built-in platform is auto-enabled only when **all** its credential env vars are present.

| Platform | Required env var(s) — ALL must be present |
| - | - |
| `telegram` | `TELEGRAM_BOT_TOKEN` |
| `discord` | `DISCORD_BOT_TOKEN` |
| `slack` | `SLACK_BOT_TOKEN` **and** `SLACK_APP_TOKEN` |
| `whatsapp` | `WHATSAPP_ACCESS_TOKEN` **and** `WHATSAPP_PHONE_NUMBER_ID` |

Multi-credential platforms (Slack, WhatsApp) stay down until every listed var is set — `SLACK_BOT_TOKEN` alone does not auto-enable Slack.

***

## Choosing an Option

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start[🚀 Starting the gateway]
    Q1{Env var set for the platform?}
    Q2{Want to customise routes/policy?}
    Q3{Want to disable a specific channel?}

    A[Just run praisonai gateway — auto-enabled]
    B[Add explicit channels: block — always wins]
    C[Set enabled: false on that channel]
    D[Set auto_enable_from_env: false — strict mode]

    Start --> Q1
    Q1 -- Yes --> Q2
    Q1 -- No --> B
    Q2 -- No --> A
    Q2 -- Yes --> B
    Start --> Q3
    Q3 -- Yes --> C
    Start --> D

    classDef start fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef answer fill:#10B981,stroke:#7C90A0,color:#fff

    class Start start
    class Q1,Q2,Q3 question
    class A,B,C,D answer
```

***

## Configuration Options

| Option | Level | Type | Default | Description |
| - | - | - | - | - |
| `auto_enable_from_env` | `gateway.yaml` top-level | `bool` | `true` | Auto-register a channel for any known platform whose credential env var(s) are all present and that isn't declared or disabled. Set to `false` to restore the strict "must declare a channel" guard. |
| `enabled` | Each `channels:` entry | `bool` | `true` | Explicit per-channel opt-out. `false` drops the channel and also suppresses auto-enable for that platform even when its token env var is set. |

***

## Precedence

```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Explicit channels: entry  >  enabled: false  >  auto-enable from env  >  strict "No channels" error
```

> [accordion] Explicit token wins over env
>
> An explicit `token:` overrides the env-resolved one — the auto-enable path never touches a platform you already declared.
>
> ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> channels:
>   telegram:
>     platform: telegram
>     token: "explicit-token"     # env-derived token is ignored
>     routes:
>       default: assistant
> ```

> [accordion] Opt out even when the token is present
>
> `enabled: false` keeps a channel down and suppresses auto-enable for that platform, even with the credential set.
>
> ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> channels:
>   telegram:
>     platform: telegram
>     enabled: false              # stays down
> ```

> [accordion] Restore strict behaviour
>
> Set `auto_enable_from_env: false` to require an explicit `channels:` block. With no channel declared, the gateway fails closed:
>
> ```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> No channels configured. Add at least one channel (telegram, discord, slack, whatsapp)
> to your config, or set a platform credential env var (e.g. TELEGRAM_BOT_TOKEN)
> to auto-enable one.
> ```
>
> ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> gateway:
>   auto_enable_from_env: false
> ```

***

## For Plugin Channel Authors

A plugin platform (registered via the `praisonai.channels` entry point or `register_platform(...)`) becomes auto-enable-able when its `ChannelDescriptor.config_fields` lets the gateway source every `required` field from the environment (each has an `env` fallback).

If a plugin has a required field without an `env` fallback (e.g. a required `server` for an IRC-like channel), the gateway leaves it for explicit configuration — auto-enabling it would seed a channel that then fails required-field validation and aborts the whole gateway. When there are no required fields, a single env-backed `secret` field is enough to identify a ready-to-use credential.

***

## Best Practices

> [accordion] Use a .env file for local development
>
> `praisonai gateway` loads `~/.praisonai/.env` into the environment without overwriting shell values, so committing an `.env.example` and running `praisonai gateway` is enough for a teammate to get a bot up.

> [accordion] Put production env vars in your process supervisor
>
> In production, set credentials in systemd (`Environment=`), Docker (`--env-file`), or your orchestrator's secret manager rather than shell dotfiles.

> [accordion] Prefer explicit channels: for shared bots
>
> Where routing, policies, or per-channel session settings matter, declare `channels:` explicitly. The zero-config path is designed for first-run and single-agent deployments.

> [accordion] Disable auto-enable on multi-tenant deployments
>
> Set `auto_enable_from_env: false` on shared deployments so no unexpected channel comes up just because a token happens to be in the environment.

***

## Related

> [card] [Gateway Overview](https://praison.ai/docs/features/gateway-overview.md)
>
> Multi-channel agent coordination and the full config surface

> [card] [Gateway CLI](https://praison.ai/docs/features/gateway-cli.md)
>
> Start, monitor, and manage the gateway from the command line

> [card] [Bot Gateway](https://praison.ai/docs/features/bot-gateway.md)
>
> Routing, approvals, and multi-agent channel wiring

> [card] [Custom Channel](https://praison.ai/docs/features/gateway-custom-channel.md)
>
> Add a plugin platform that self-describes its credential fields


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.