Skip to main content
Interactive wizard that configures messaging bots and automatically installs the daemon service to run them in the background.

​
Quick Start

1

Run the onboard wizard

# Zero prompts once you have the token — wizard configures the bot
# and installs the background daemon automatically.
praisonai onboard
Once tokens are collected, the daemon is installed automatically by default. Run praisonai gateway uninstall if you don’t want it.
2

Configure your channels

The wizard guides you through channel setup with an interactive flow:
  1. Choose first platform — Telegram, Discord, Slack, or WhatsApp
  2. Enter bot token — Hidden input, validated against the platform API
  3. Add another bot channel? — Create multiple bots on the same platform for different roles
  4. Enter role (if adding more) — Role name like cfo, ops, content for specialized agents
  5. Configure security — Allowed user IDs for each channel (comma-separated)
The wizard automatically generates environment variables following the PLATFORM_<ROLE>_BOT_TOKEN convention.
3

You're done

The wizard writes bot configuration to ~/.praisonai/bot.yaml, stores tokens/secrets in ~/.praisonai/.env only (chmod 600), and shows the ✅ Done panel with your dashboard URL.

​
How It Works

The onboarding process follows these phases:
PhaseDescription
Platform SelectionChoose Telegram, Discord, Slack, or WhatsApp
Token EntryPaste the bot token for your chosen platform and validate it against the platform API
Security SetupSet allowed user IDs (or leave blank for open access)
Daemon InstallSets up the platform daemon (launchd/systemd/Windows Task)
ConfigurationWrites config files to ~/.praisonai/
CompletionShows the ✅ Done panel with all connection details

​
What The Wizard Writes

FileContents
~/.praisonai/bot.yamlChannel configurations, multi-platform/multi-role routing, token env-var references, specialized agents
~/.praisonai/.envBot token(s) with role-based naming, *_ALLOWED_USERS, GATEWAY_AUTH_TOKEN (chmod 600)
ComponentLocationPurpose
Platform daemonSystem service (launchd/systemd/Windows Task)Keeps bot running in background
Bot configuration~/.praisonai/config/Stores tokens and settings
Gateway auth token~/.praisonai/.env (mode 0600)Authentication for web dashboard
Dashboard URLPrinted in Done panelLocal web interface
Agent name (assistant) and instructions ("You are a helpful AI assistant.") use sensible defaults — edit ~/.praisonai/bot.yaml to customise. The file contains the full schema as inline documentation.

​
Generated bot.yaml example

channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    allowed_users: ${TELEGRAM_ALLOWED_USERS}
    ack_emoji: "⏳"            # Show processing indicator during long agent operations
    done_emoji: "✅"           # Replace ack_emoji when operation completes
Ack and done emojis are pre-populated so freshly onboarded bots give visible feedback during long agent operations from the start.
Upgrading? Older bot.yaml files may contain a home_channel key (for example, home_channel: ${TELEGRAM_HOME_CHANNEL} or the equivalent for Discord / Slack / WhatsApp). This was never read by the gateway and is safe to delete. Re-running praisonai onboard and accepting the overwrite regenerates a clean file.
Auth token is now auto-persisted to ~/.praisonai/.env with secure permissions (mode 0600) and shown as fingerprint gw_****XXXX in logs for security.

​
The ✅ Done Panel

When onboarding completes, you’ll see a comprehensive summary panel with four main sections: 
╭─ ✅ Done ──────────────────────────────────────────────────────╮
│ Setup complete! Your bot is now running in the background.     │
│                                                                │
│ 🦞 Dashboard UI:                                               │
│   praisonai claw          → http://127.0.0.1:8082              │
│                                                                │
│ Gateway endpoints:                                             │
│   Health (public):  http://127.0.0.1:8765/health               │
│   Info (authed):    http://127.0.0.1:8765/info?token=…         │
│   Token abcd…wxyz stored in ~/.praisonai/.env as               │
│   GATEWAY_AUTH_TOKEN                                           │
│                                                                │
│ Manage the daemon:                                             │
│   praisonai gateway status     # is it running?                │
│   praisonai gateway logs       # tail the logs                 │
│   launchctl kickstart -k gui/$(id -u)/ai.praison.bot           │
│   praisonai gateway uninstall  # remove the daemon             │
│                                                                │
│ Re-run or reconfigure:                                         │
│   praisonai onboard            # change tokens / add platforms │
│   praisonai gateway start      # run in foreground (no daemon) │
│   praisonai doctor             # diagnose the whole stack      │
╰────────────────────────────────────────────────────────────────╯
The headline changes based on daemon install success:
  • Success: “Setup complete! Your bot is now running in the background.”
  • Failed: “Setup complete! Configuration complete.”

​
Re-running Onboarding

The wizard is idempotent - safe to run multiple times: 
# Update an existing bot's token
praisonai onboard

# Switch from Telegram to Discord
praisonai onboard
Re-running the wizard will:
  • Update tokens and configurations in place
  • Skip daemon installation if already installed and running (prints ✓ Daemon already installed and running)
  • Preserve existing chat histories and agent memory
The config file path is always ~/.praisonai/bot.yaml (no longer prompted for). When re-running, the overwrite prompt now says {path} exists. Overwrite with fresh config? with Kept existing file on decline.
If the daemon is already installed, re-running praisonai onboard is a no-op for the daemon service. Only configuration files are updated.

​
Adding Multiple Bots on the Same Platform

The wizard now supports creating multiple specialized bots on the same platform for different roles: 
# Example wizard flow
praisonai onboard
# Choose telegram
# Enter first bot token
# "Add another bot channel?" → Yes
# "Role for this Telegram bot?" → cfo
# Enter CFO bot token
# "Add another bot channel?" → Yes  
# "Role for this Telegram bot?" → ops
# Enter Ops bot token
This creates environment variables with role-based naming: 
TELEGRAM_BOT_TOKEN=123456789:ABC...          # Main bot
TELEGRAM_CFO_BOT_TOKEN=987654321:DEF...     # CFO bot
TELEGRAM_OPS_BOT_TOKEN=456789123:GHI...     # Ops bot
TELEGRAM_ALLOWED_USERS=123456789,987654321
The generated bot.yaml will contain multiple channels routing to specialized agents. See the Multi-Channel Bots guide for complete documentation.

​
Relationship to Setup

PraisonAI has two configuration commands that run in sequence:
  • praisonai setup - Configures LLM providers (OpenAI, Anthropic, etc.)
  • praisonai onboard - Configures messaging bots (Telegram, Discord, etc.)
Both are called automatically by the installer, but can be run independently.

​
Common Patterns

​
Skip onboarding during install

# Skip during installation
curl -fsSL https://praison.ai/install.sh | bash -s -- --no-onboard

# Or via environment variable
PRAISONAI_NO_ONBOARD=1 curl -fsSL https://praison.ai/install.sh | bash

​
Run onboarding separately later

# Install first without onboarding
curl -fsSL https://praison.ai/install.sh | bash -s -- --no-onboard

# Set up LLM keys
praisonai setup

# Set up messaging bot when ready
praisonai onboard

​
Switch platforms

# Currently using Telegram, switch to Discord
praisonai onboard
# Choose Discord and enter Discord bot token

​
Re-generate auth token

# Run onboarding again to get a fresh auth token
praisonai onboard

​
Which Platform Should I Use?

Choose based on:
PlatformBest ForSetup DifficultyFeatures
TelegramPersonal use, experimentationEasyRich bot API, inline keyboards
DiscordGaming communities, developer teamsMediumVoice channels, rich embeds
SlackBusiness teams, professional workflowsMediumThread support, workspace integration
WhatsAppCustomer support, global reachHardBusiness accounts required

​
Best Practices

Telegram has the simplest setup process and most permissive API limits. Use it for initial testing before moving to your target platform.
Bot tokens are stored in ~/.praisonai/.env. Ensure this file has proper permissions (600) and exclude it from version control.
After onboarding, visit the dashboard URL from the Done panel to confirm the web interface is working and authentication is set up correctly.
If bots aren’t responding or services seem down, run praisonai doctor for diagnostic information and common fixes. If you onboarded multiple bots on one platform and see Unknown channel 'telegram_<role>' from praisonai doctor, upgrade to a release that includes PR #1772. Older releases incorrectly rejected the multi-channel YAML their own onboard wizard produced.

Bind-Aware Authentication

Gateway and UI security behavior based on bind interface

Installation Guide

Complete installer documentation including onboarding flow

Dashboard

Web dashboard for managing agents and monitoring bots

Bot Security

Security best practices for messaging bots

Quick Install

One-liner installation including onboarding prompt