![GitHub]([] ![Build]([] ![docker hub]([] ![docker image arch]([] ![docker image size]([***] !license

Chibi is a Python-based *** 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).

GitHub

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)

Features

• Multi-Provider Support: Interact with models from 7 different providers (see list above).
• Seamless Provider Switching: Change the underlying LLM provider anytime without losing the current conversation context. The history is automatically adapted for the new model.
• Image Generation: Request images using DALL-E (OpenAI), Gemini (Google), or Grok (xAI) directly within the chat.
• 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 simply keep it in memory (lost on restart).
• Optional "Public Mode": Run the bot without a master API key. Each user will be prompted to provide their own key via private message to the bot.
• User and Group Whitelists: Restrict bot access to specific users or chat groups.
• Easy Deployment with Docker: Pre-configured Docker image 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.
• Configurable: Extensive options via environment variables.
• 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

Using Docker Run

1. Pull the Chibi Docker image:

   shell
   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 *** token and at least one AI provider API key. Data is not persisted between restarts.

   shell
   docker run -d --name chibi \
    -e ***_BOT_TOKEN='YOUR_***_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.

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 ***_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.

yaml
version: '3.8'

services:
  chibi:
    image: pysergio/chibi:latest
    restart: unless-stopped
    environment:
      # Required: Get from BotFather
      ***_BOT_TOKEN: ${***_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 ---
# ***_BOT_TOKEN=***: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.

yaml
version: '3.8'

services:
  chibi:
    image: pysergio/chibi:latest
    restart: unless-stopped
    environment:
      # --- Required ---
      ***_BOT_TOKEN: ${***_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_***_username,***" # 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 ---
# ***_BOT_TOKEN=***: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.

yaml
version: '3.8'

services:
  chibi:
    image: pysergio/chibi:latest
    restart: unless-stopped
    environment:
      # Required: Get from BotFather
      ***_BOT_TOKEN: ${***_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,***"
      # 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 ---
# ***_BOT_TOKEN=***:ABC-DEF1234...
# (No API keys needed here for public mode)
# -------------------------

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

*** 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

Image Generation Settings

Whitelists

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): [***]
• Anthropic (Claude): [***] (Sign up and navigate to API Keys)
• Cloudflare: [***] (Need API key with Account.Workers AI permissions)
• DeepSeek: [***] (Sign up and navigate to API Keys)
• Google (Gemini): [***]
• MistralAI: [***] (Sign up and navigate to API Keys)
• MoonshotAI (Kimi): [***] (Sign up and navigate to API Keys)
• OpenAI (GPT & DALL-E): [***]
• xAI (Grok): [***] (Check documentation for API access details)

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.