Supported platforms

Chibi is a Python-based Telegram chatbot that allows users to interact with a variety of powerful large language models (LLMs) and image generation models. The bot is asynchronous, providing fast response times and serving multiple users simultaneously without blocking each other's requests. Chibi supports session management, enabling models to remember the user's conversation history. The conversation history is stored for a configurable duration and is preserved even if the bot is restarted (when using persistent storage).

Docker Hub

Supported platforms

Currently supported architectures:

• linux/amd64
• linux/arm64

Note on armv7: Support for the linux/armv7 architecture was discontinued after version 0.8.2. However, if there is sufficient user interest, resuming armv7 builds can be investigated.

Supported providers

Chibi currently supports models from the following providers:

• Alibaba (Qwen models)
• Anthropic (Claude models)
• Cloudflare (44+ open-source models)
• DeepSeek
• Google (Gemini models, including image generation)
• MistralAI
• MoonshotAI
• OpenAI (including DALL-E for images)
• xAI (Grok models, including image generation)
• ElevenLabs (ElevenLabs models, including text to speech, speech to text, music generation)
• MiniMax (Minimax models, text to speech)

Features

• Expanded AI Provider Support: Interact with a wider range of leading LLM and image generation models from various providers, including OpenAI, Google (Gemini), Anthropic, Alibaba, Deepseek, Grok, MoonshotAI, Cloudflare, and custom OpenAI-compatible endpoints.
• Seamless Provider Switching: Change the underlying LLM provider anytime without losing the current conversation context. The history is automatically adapted for the new model.
• Advanced Tooling & Recursive Delegation: The bot leverages an enhanced suite of built-in tools for tasks like file system operations (with FILESYSTEM_ACCESS setting), terminal command execution (with LLM-moderated access), web searching, and more. Recursive delegation allows sub-agents to handle complex, multi-step tasks efficiently, significantly reducing token usage.
• Initial Voice Interaction: Engage with the bot using voice messages and receive audio responses. This is an initial implementation with ongoing development planned for richer voice capabilities.
• Configurable Image Generation: Request images with Nano Banana, Imagen, Wan/Qwen, DALL-E or Grok, with enhanced control over quality, size, aspect ratio, and quantity per request.
• Music Generation: Generate high-quality music via Suno AI by describing the style and lyrics. Use the /image_model command to see if Suno is available or simply ask the bot to "compose a song".
• Context Management:
  • Automatic conversation summarization (optional) to save tokens on long conversations by replacing older parts of the history with a summary.
  • Manual context reset (/reset command) to start fresh and save tokens.
• Flexible Session Storage: Store conversation history locally (requires mounting a volume for persistence), in Redis, or DynamoDB, or simply keep it in memory (lost on restart).
• Optional "Public Mode": Run the bot without master API keys. Each user will be prompted to provide their own key via private message to the bot.
• Granular Access Control: Restrict bot access to specific users or chat groups, whitelist allowed models, and control image generation limits for certain users.
• Dynamic Proxy Support: Configure HTTP/SOCKS proxies for AI provider API requests and heartbeat pings, separate from the Telegram proxy.
• Health Monitoring (Heartbeat): The bot can periodically ping a configured URL (e.g., a healthchecks.io endpoint) to signal its operational status, allowing external systems to monitor its health and availability.
• Easy Deployment with Docker: Pre-configured Docker images (including experimental ARMv7 support) ready to run with minimal setup. Public mode works out-of-the-box without needing API keys in the environment variables.
• Low Resource Usage: Runs efficiently even on low-spec hardware like a Raspberry Pi 4.
• Asynchronous: Fast, non-blocking performance.
• Highly Configurable: Extensive options via environment variables for fine-grained control over bot behavior.
• MIT Licensed: Open source and free to use.

System Requirements

Chibi is designed to be very resource-efficient. It runs smoothly on hardware like a Raspberry Pi 4 (or higher) or even minimal cloud instances such as an AWS EC2 t4g.nano (2 arm64 vCPUs, 512MB RAM), capable of serving multiple users concurrently.

Essentially, the main requirements are:

• A machine running on a supported architecture (linux/amd64 or linux/arm64).
• Docker installed and running on that machine.

Prerequisites

• Docker
• Docker Compose (optional)

Getting Started

Quick Install: Dobby Agent Mode (Experimental)

⚠️ WARNING: This installation mode enables full filesystem access. Only use on trusted systems.

Dobby is an experimental agent mode that gives the bot access to your filesystem and shell commands. Perfect for development assistance, automation, and advanced AI interactions.

curl -fsSL https://raw.githubusercontent.com/s-nagaev/chibi/main/scripts/install.sh | bash

What you get:

• Autonomous AI agent with filesystem access
• Pre-configured for agent workflows
• Simple command-line interface: dobby run, dobby attach, dobby free
• 200K token context window (extended conversations)
• Whitelisted access only (security first)

Requirements:

• Telegram Bot Token (required)
• At least one AI provider API key
• User whitelist configuration

See scripts/README.md for full installation guide and security considerations.

Standard Installation (Docker)

Using Docker Run

1. Pull the Chibi Docker image:

   docker pull pysergio/chibi:latest
   

2. Run the Docker container with the necessary environment variables: This command runs the bot in private mode using a Google Gemini key. It requires your Telegram token and at least one AI provider API key. Data is not persisted between restarts.

   docker run -d --name chibi \
    -e TELEGRAM_BOT_TOKEN='YOUR_TELEGRAM_TOKEN' \
    -e GEMINI_API_KEY='AIzaSyYourGeminiKey...' \
    # Add other keys like -e OPENAI_API_KEY='sk-...' if needed
    pysergio/chibi:latest
   

Replace placeholders with your actual values. Hint: talk to BotFather on Telegram and use the /newbot command to create a bot and get your token.

Docker Compose Examples

Here are a few examples to get you started with docker-compose. Remember to create a .env file in the same directory as your docker-compose.yml to store your secrets like TELEGRAM_BOT_TOKEN and API keys.

Minimal Private Mode Example

This is the bare minimum setup to run Chibi in private mode. It uses the OpenAI API key provided in your .env file.

version: '3.8'

services:
  chibi:
    image: pysergio/chibi:latest
    restart: unless-stopped
    environment:
      # Required: Get from BotFather
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}

      # Required for Private Mode: Add at least one provider API key
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      # Add other keys (GEMINI_API_KEY, ANTHROPIC_API_KEY, etc.) here if needed

# --- .env file example ---
# TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234...
# OPENAI_API_KEY=sk-YourOpenAIKey...
# -------------------------

Advanced Private Mode Example

This example shows a more customized setup for private mode:

• Uses multiple AI providers.
• Stores conversation history locally and persistently using a Docker volume.
• Sets user/group whitelists.
• Defines a custom assistant prompt and default model.
• Sets a monthly limit for image generations.

version: '3.8'

services:
  chibi:
    image: pysergio/chibi:latest
    restart: unless-stopped
    environment:
      # --- Required ---
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}

      # --- API Keys (add whichever you use) ---
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      GEMINI_API_KEY: ${GEMINI_API_KEY}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      # ... add other provider keys as needed

      # --- Whitelists ---
      USERS_WHITELIST: "@your_telegram_username,123456789" # Usernames and User IDs
      GROUPS_WHITELIST: "-100987654321" # Group Chat IDs (usually negative)

      # --- Customization ---
      BOT_NAME: "MyChibiBot"
      ASSISTANT_PROMPT: "You are a specialized assistant for code reviews."
      MODEL_DEFAULT: "gpt-4o" # Set your preferred default model

      # --- Limits & History ---
      MAX_HISTORY_TOKENS: 8000 # Adjust context window size
      IMAGE_GENERATIONS_LIMIT: 20 # Monthly limit per user (requires volume)

      # --- Storage ---
      # LOCAL_DATA_PATH: /app/data # Default path

    volumes:
      # Mounts the 'chibi_data' volume for persistence
      - chibi_data:/app/data

volumes:
  # Defines the Docker volume
  chibi_data: {}

# --- .env file example ---
# TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234...
# OPENAI_API_KEY=sk-YourOpenAIKey...
# GEMINI_API_KEY=AIzaSy...
# ANTHROPIC_API_KEY=sk-ant-...
# -------------------------

Public Mode Example

This setup runs the bot in public mode. No master API keys are needed here; the bot will ask each user to provide their own key via private message.

version: '3.8'

services:
  chibi:
    image: pysergio/chibi:latest
    restart: unless-stopped
    environment:
      # Required: Get from BotFather
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}

      # --- Enable Public Mode ---
      PUBLIC_MODE: "True"

      # --- Optional Customization ---
      BOT_NAME: "ChibiPublic"
      # HIDE_MODELS: "True"
      # HIDE_IMAGINE: "True"

      # --- Whitelists (Optional for Public Mode) ---
      # You can still restrict *which* users/groups can use the bot
      # USERS_WHITELIST: "allowed_user1,123456789"
      # GROUPS_WHITELIST: "-1001122334455"

    # Volumes are optional unless needed for IMAGE_GENERATIONS_LIMIT
    # or specific local storage needs.
    # volumes:
    #   - chibi_public_data:/app/data

# volumes:
#   chibi_public_data: {}

# --- .env file example ---
# TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234...
# (No API keys needed here for public mode)
# -------------------------

Please, visit the examples directory of the current repository for more examples.

Telegram Bot Settings

General Application Settings

Storage Settings

API Keys (Master Keys)

These keys are used when PUBLIC_MODE is False. If PUBLIC_MODE is True, these are ignored (users provide their own keys).

Model & Conversation Settings### MCP Settings

Image Generation Settings

Whitelists

Whitelist variables have been moved to their respective sections (e.g., USERS_WHITELIST and GROUPS_WHITELIST are now under Telegram Bot Settings, MODELS_WHITELIST under Model & Conversation Settings, and IMAGE_GENERATIONS_WHITELIST under Image Generation Settings).

Heartbeat

Metrics & Monitoring

Getting API Keys

To use Chibi in private mode, or for users interacting with the bot in public mode, you'll need API keys from the desired AI providers. Here's where you can typically find information or generate keys:

• Alibaba (Qwen via DashScope): https://dashscope.console.aliyun.com/apiKey
• Anthropic (Claude): https://console.anthropic.com/ (Sign up and navigate to API Keys)
• Cloudflare: https://dash.cloudflare.com/profile/api-tokens (Need API Key with Account.Workers AI permissions)
• DeepSeek: https://platform.deepseek.com/ (Sign up and navigate to API Keys)
• Google (Gemini): https://aistudio.google.com/app/apikey
• MistralAI: https://console.mistral.ai/ (Sign up and navigate to API Keys)
• MoonshotAI (Kimi): https://platform.moonshot.cn (Sign up and navigate to API Keys)
• OpenAI (GPT & DALL-E): https://platform.openai.com/api-keys
• xAI (Grok): https://docs.x.ai/ (Check documentation for API access details)
• ElevenLabs (Music, STT, TTS): https://elevenlabs.io/ (Sign up and navigate to API Keys)
• Suno (Music, Unofficial API): https://sunoapi.org (Sign up and navigate to API Keys)
• MiniMax (TTS): https://api.minimax.io/ (Sign up and navigate to API Keys)

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.