pysergio/chibi repository overview

⁠Chibi

Self-hosted, asynchronous Telegram bot that orchestrates multiple AI providers, tools, and sub-agents to get real work done.

⁠Quick Start

Get Chibi running in under 2 minutes.

Prerequisites: Docker, a Telegram Bot Token⁠, and at least one AI provider API key.

docker run -d \
  --name chibi \
  -v chibi_data:/app/data \
  -e TELEGRAM_BOT_TOKEN=your_bot_token_here \
  -e USERS_WHITELIST=your_telegram_id_or_nickname \
  -e OPENAI_API_KEY=sk-... \
  pysergio/chibi:latest

Verify it works: Open Telegram, find your bot, and send /start.

⁠What is Chibi?

Chibi is a Telegram-based digital companion that orchestrates multiple AI providers and tools to deliver outcomes — code changes, research syntheses, media generation, and operational tasks.

Built for the moment you need more than "an AI tool": a partner that coordinates models, runs work in the background, and integrates with your systems.

Key Features:

• One interface (Telegram). Mobile, desktop, web — always with you.
• Provider-agnostic. Use the best model for each task, no vendor lock-in.
• Autonomous execution. Sub-agents work in parallel; long tasks run asynchronously.
• Tool-connected. Filesystem, terminal, and MCP integrations (GitHub, browser, DBs, etc.).
• Self-hosted. Your data, your keys, your rules.

Supported Providers: LLMs: OpenAI · Anthropic · Google Gemini · DeepSeek · xAI · Mistral AI · Alibaba (Qwen) · Moonshot AI · MiniMax · ZhipuAI · Cloudflare Workers AI OpenAI-compatible: Ollama · vLLM · LM Studio · any OpenAI-compatible API Image Generation: Google (Imagen, Nano Banana) · OpenAI (DALL·E) · Alibaba · xAI · Wan · ZhipuAI · MiniMax Music: Suno · Voice: ElevenLabs · MiniMax · OpenAI (Whisper)

⁠Supported Tags and Architectures

⁠Tags

• latest — most recent stable release
• vX.Y.Z (e.g., v2.5.0) — specific version, pinned
• vX.Y (e.g., v2.5) — latest patch within a minor version

⁠Architectures

All tags are multi-arch manifests — Docker automatically pulls the correct image for your platform.

⁠Docker Compose Example

Recommended for production deployments. Redis enables persistent conversation history across container restarts.

Create a compose.yaml:

services:
  chibi:
    image: pysergio/chibi:latest
    container_name: chibi
    restart: unless-stopped
    depends_on:
      - redis
    volumes:
      - chibi_data:/app/data
      - ./skills:/app/skills:ro    # Custom skills (optional, read-only)
    environment:
      # Required
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
      USERS_WHITELIST: ${USERS_WHITELIST}
      REDIS_URL: redis://redis:6379/0

      # At least one AI provider
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      # ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      # GEMINI_API_KEY: ${GEMINI_API_KEY}

      # Optional: Agent mode
      # FILESYSTEM_ACCESS: "true"
      # ENABLE_MCP_STDIO: "true"
    env_file:
      - .env

  redis:
    image: redis:alpine
    container_name: chibi-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data

volumes:
  chibi_data:
  redis_data:

Create a .env file alongside it:

TELEGRAM_BOT_TOKEN=your_bot_token_here
USERS_WHITELIST=your_telegram_id
OPENAI_API_KEY=sk-...

Then start:

docker compose up -d

⁠Environment Variables

⁠Required

⁠AI Providers

At least one provider API key is required.

For the full list of environment variables (50+), see the Configuration Reference⁠.

⁠Volumes and Persistence

# Backup data volume
docker run --rm -v chibi_data:/data -v $(pwd):/backup alpine tar czf /backup/chibi-backup.tar.gz /data

⁠Model Context Protocol (MCP)

Chibi connects to MCP servers dynamically at runtime — there is no static configuration file to mount. The AI agent uses built-in tools to establish and manage MCP connections on demand:

• initialize_stdio_mcp_server — connect to an MCP server via stdio (e.g., a local CLI tool).
• initialize_sse_mcp_server — connect to an MCP server via SSE (e.g., a remote HTTP endpoint).
• deinitialize_mcp_server — disconnect from a previously connected server.

Once connected, the MCP server's tools are automatically registered and become available to the agent for the duration of the session.

Environment variables:

Example usage (from Telegram):

Simply ask the bot to connect to an MCP server. The agent will call the appropriate tool internally.

No config files needed — MCP is fully managed through the conversation.

⁠Security

Chibi ships with secure defaults:

• Runs as non-root user (chibi)
• Filesystem access disabled by default
• Only whitelisted users can interact with the bot
• Delegation enabled but restrictable via TOOLS_WHITELIST

Best Practices:

1. Always set USERS_WHITELIST — never run without it
2. Keep FILESYSTEM_ACCESS=false unless you need agent mode
3. Store API keys in .env files or Docker secrets, never in compose files
4. Use TOOLS_WHITELIST to restrict available tools in production

Read-only filesystem (enhanced security):

docker run --read-only \
  -v chibi_data:/app/data \
  -v /tmp:/tmp \
  -v /var/run:/var/run \
  pysergio/chibi:latest

⁠Troubleshooting

Bot not starting?

1. Check logs: docker logs chibi
2. Verify TELEGRAM_BOT_TOKEN is correct
3. Ensure USERS_WHITELIST contains your Telegram ID

Cannot connect to a provider?

1. Verify the API key is set correctly
2. Check network connectivity from the container
3. Review API key permissions in the provider's dashboard

Data not persisting?

1. Always use named volumes: -v chibi_data:/app/data
2. Check volume mount permissions

⁠Updating

docker pull pysergio/chibi:latest
docker compose up -d

⁠License

MIT License — see LICENSE⁠.

⁠Resources

• Documentation: https://chibi.bot⁠
• GitHub: https://github.com/s-nagaev/chibi⁠
• Configuration Reference: https://chibi.bot/configuration⁠
• Installation Guide: https://chibi.bot/installation⁠
• Issues & Support: https://github.com/s-nagaev/chibi/issues⁠