Local Setup

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

Prerequisites

• Python 3.11+
• uv (Python package manager)
• PostgreSQL (for data storage)

Install dependencies

pip install uv
uv sync

Configure environment

cp .env.example .env

Edit .env with your credentials. At minimum:

• An LLM API key
• At least one messaging channel:
  • iMessage: pick one backend. Linq (LINQ_API_TOKEN + LINQ_FROM_NUMBER) for hosted iMessage/RCS/SMS, or BlueBubbles (BLUEBUBBLES_SERVER_URL + BLUEBUBBLES_PASSWORD) for a self-hosted bridge. The app surfaces either as a single “iMessage” channel to users. Configuring both at once is not supported.
  • Telegram: TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_CHAT_ID

Set up PostgreSQL

Create the development database:

createdb -U clawbolt clawbolt

Run migrations:

uv run alembic upgrade head

Start the server

uv run uvicorn backend.app.main:app --reload

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

File storage in development

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

Set up a messaging webhook

Without Docker, you need a tunnel to give messaging providers a public URL:

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

If using the iMessage channel backed by Linq, the webhook registers automatically when the server detects the tunnel URL. If using BlueBubbles as the iMessage backend, configure the webhook on your BlueBubbles server per its setup guide.

If using Telegram, copy the tunnel URL and register the webhook manually:

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

See Linq Setup, BlueBubbles Setup, or Telegram Setup for details.