Docker

Docker Compose is the recommended way to run Clawbolt. It handles the app and tunnel setup.

Quick start

# Clone and configure
git clone https://github.com/mozilla-ai/clawbolt.git
cd clawbolt
cp .env.example .env
# Edit .env with your credentials

# Start everything
docker compose up --build

What Docker Compose starts

Service	Description
app	FastAPI server on port 8000
db	PostgreSQL database for all structured data
tunnel	Cloudflare Tunnel for HTTPS webhook registration

On startup, the app:

1. Runs database migrations automatically
2. Starts the FastAPI server
3. Auto-registers webhooks via the Cloudflare Tunnel URL (Telegram and, if Linq is the configured iMessage backend, Linq)

Data persistence

Structured data (users, messages, memory, etc.) is stored in PostgreSQL. The Docker Compose file includes a PostgreSQL service with a named volume for persistence.

File uploads and media are stored under the data/ directory. By default, Docker Compose bind-mounts ./data from your host into the container at /app/data.

Verify it’s running

curl http://localhost:8000/api/health
# {"status":"ok"}

Troubleshooting

Docker build fails with dependency errors

Try rebuilding without cache:

# Rebuild without cache
docker compose build --no-cache

Port 8000 already in use

# Stop existing containers
docker compose down

# Or use a different port
docker compose up --build -e APP_PORT=8080

Reset all data

# Remove all user data
rm -rf data/users/
docker compose up --build