Standalone Bot YAML

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

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.

How It Works

Config Structure

Quick Start

Install

pip install praisonaiagents "praisonai-bot[gateway,bot]"

Set credentials

export OPENAI_API_KEY=your_openai_api_key
export TELEGRAM_BOT_TOKEN=your_telegram_token

Create bot.yaml

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}

Start the gateway with your YAML

praisonai-bot gateway start --config bot.yaml

The gateway registers the agent and starts all configured channel bots automatically.

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.

Single-platform shorthand

For one platform, declare a top-level platform: (and optionally token:) instead of a platforms: map:

platform: telegram
token: "${TELEGRAM_BOT_TOKEN}"

token: is optional — omit it and the declared platform: resolves the platform’s own documented env var (TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, etc.):

platform: telegram

The declared platform always wins. If other platform credentials are exported in the environment, bot start refuses to auto-enable them and logs a warning:

WARNING Config declares 'platform: telegram'; NOT auto-enabling discord, slack
despite their credentials being present in the environment. The declared
platform wins. To run them too, list them under 'channels:' explicitly.

Earlier versions could silently start the wrong platform if unrelated credentials were set. Now the declared platform always wins — list multiple platforms under channels: explicitly to run them together.

Bot startup exit codes: praisonai bot start now exits 1 on any startup failure (bad config path, missing token, unknown platform). This makes systemd Restart=on-failure and if praisonai bot start ... ; then scripting work as expected.

Shell execution keys

Add these per-channel keys to let a bot run shell commands with approval routing.

Key pattern	Type	Default	Description
`<name>.allow_shell`	`bool`	`False`	Opt in shell execution. Injects `execute_command`, lifts the deny-list entry, and appends a permission-grant line to instructions.
`<name>.auto_approve_shell`	`bool`	`True`	Runs every shell call immediately only on a loopback-bound gateway + non-group channel. On externally-bound gateways or any channel with a `group_policy`, the gateway automatically downgrades this to an approval backend (see `<name>.auto_approve_shell_acknowledge_exposed`).
`<name>.auto_approve_shell_acknowledge_exposed`	`bool`	`False`	Explicit acknowledgement that blanket auto-approval is safe on this externally-exposed or multi-user channel. Set to `true` (with `auto_approve_shell: true`) to keep the blanket behaviour on `0.0.0.0` binds or group channels. Off by default — the gateway fails closed to approval.
`<name>.approval_channel`	`str`	`None`	Where the approval prompt is delivered (platform-specific ID).
`<name>.approval_users`	`str` \| `list[str]`	`None`	Approver allowlist. Comma-separated string or list.
`<name>.approval_mode`	`str`	`None` (= `channel`)	Backend selector: `channel`, `gateway`, `http`, `webhook`. Typos raise `ValueError`.
`<name>.approval_webhook_url`	`str`	`None`	HTTPS URL for `approval_mode: webhook`.
`<name>.approval_http_host`	`str`	`"127.0.0.1"`	HTTP dashboard host for `approval_mode: http`.
`<name>.approval_http_port`	`int`	`8899`	HTTP dashboard port for `approval_mode: http`.

Bot Shell Execution

Full routing ladder, per-platform ID resolution, and recipes.

Environment Variable Interpolation

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

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

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

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

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

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.

# Good
platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}

# Never do this
platforms:
  telegram:
    token: 1234567890:ABCdef...

Run praisonai-bot gateway doctor before going live

praisonai-bot gateway doctor --config bot.yaml

This validates every channel token before starting, so a bad token fails fast instead of silently reconnecting. It also prints a credential availability table for token, app_token, and verify_token — including the secret-reference form — without revealing any value.

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.

Standalone Bot Gateway (Python)

Python API equivalent — register agents programmatically

Gateway CLI

Full list of gateway CLI commands

BotOS

Multi-platform bot orchestration

praisonai-bot SDK

Full bot-tier SDK reference

​How It Works

​Config Structure

​Quick Start

​Config Options Reference

​agent section

​gateway section

​platforms section

​Single-platform shorthand

​Shell execution keys

Bot Shell Execution

​Environment Variable Interpolation

​When to Pick YAML vs Python

​Common Patterns

​Multi-platform setup

​Custom port from environment

​Best Practices

​Related

Standalone Bot Gateway (Python)

Gateway CLI

BotOS

praisonai-bot SDK

How It Works

Config Structure

Quick Start

Config Options Reference

`agent` section

`gateway` section

`platforms` section

Single-platform shorthand

Shell execution keys

Environment Variable Interpolation

When to Pick YAML vs Python

Common Patterns

Multi-platform setup

Custom port from environment

Best Practices

Related