Skip to content
Clawbolt

Local Setup

For development, you can run Clawbolt directly with Python and uv.

Prerequisites

Section titled “Prerequisites”
  • Python 3.11+
  • uv (Python package manager)
  • PostgreSQL (or use SQLite for quick testing)

Install dependencies

Section titled “Install dependencies”
Terminal window
pip install uv
uv sync

Configure environment

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

Edit .env with your credentials. At minimum:

  • TELEGRAM_BOT_TOKEN
  • An LLM API key
  • DATABASE_URL pointing to your PostgreSQL instance
  • TELEGRAM_ALLOWED_CHAT_IDS or TELEGRAM_ALLOWED_USERNAMES — set to * to allow everyone, or a comma-separated list. Messages are rejected by default when both are empty.

Run database migrations

Section titled “Run database migrations”
Terminal window
uv run alembic upgrade head

Start the server

Section titled “Start the server”
Terminal window
uv run uvicorn backend.app.main:app --reload

The server starts on http://localhost:8000.

File storage in development

Section titled “File storage in development”

The default storage provider is local, which saves files to data/storage/ on disk. No cloud credentials needed.

Terminal window
# Uploaded files appear here:
ls data/storage/

Set up the Telegram webhook

Section titled “Set up the Telegram webhook”

Without Docker, you need to set up a tunnel manually:

Terminal window
# Install cloudflared, then:
cloudflared tunnel --url http://localhost:8000


# Copy the tunnel URL and register the webhook:
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://<tunnel-url>/api/webhooks/telegram"}'

See Telegram Setup for details.