Skip to content
Clawbolt

Getting Started

The fastest way to run Clawbolt is with Docker Compose. This starts PostgreSQL and the app together.

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose
  • A Telegram bot token (see Telegram Setup)
  • An LLM provider API key (OpenAI, Anthropic, etc.)

1. Clone the repository

Section titled “1. Clone the repository”
Terminal window
git clone https://github.com/mozilla-ai/clawbolt.git
cd clawbolt

2. Configure environment

Section titled “2. Configure environment”
Terminal window
cp .env.example .env

Edit .env and fill in the required credentials. See Configuration for full details.

At minimum you need:

  • TELEGRAM_BOT_TOKEN — your Telegram bot token
  • An LLM API key (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
  • TELEGRAM_ALLOWED_CHAT_IDS or TELEGRAM_ALLOWED_USERNAMES — controls who can message the bot. Set to * to allow everyone, or a comma-separated list of IDs/usernames. Messages are rejected by default when both are empty.
  • VISION_MODEL — the model used for image analysis (defaults to LLM_MODEL if not set)

3. Start the services

Section titled “3. Start the services”
Terminal window
docker compose up --build

This will:

  • Start a PostgreSQL 16 database
  • Build the app image (Python 3.11, ffmpeg for audio processing)
  • Run Alembic migrations to create the database schema
  • Start the FastAPI server on port 8000

4. Verify it’s running

Section titled “4. Verify it’s running”
Terminal window
curl http://localhost:8000/api/health
# {"status":"ok"}

5. Start chatting

Section titled “5. Start chatting”

The Telegram webhook is registered automatically: Docker Compose starts a Cloudflare Tunnel alongside the app and calls setWebhook on startup. No Cloudflare account or auth token required.

Send a message to your bot on Telegram and Clawbolt will respond.

Next steps

Section titled “Next steps”