Skip to content
Thunderbolt

Quick Start

This walks through running Thunderbolt locally: backend API, PowerSync sync service, and the Vite frontend.

Prerequisites

After cloning, run make doctor — it inspects your machine and prints exact install commands for anything missing. The most common needs are:

  • Bun 1.2+
  • Rust toolchain — for Tauri desktop and mobile builds (install via rustup)
  • sccache — optional; make setup installs it when Cargo is available to speed up Rust rebuilds
  • Docker — PowerSync and PostgreSQL run in containers during local dev

You’ll also need at least one AI provider API key — Anthropic, OpenAI, Mistral, Fireworks, or any OpenAI-compatible endpoint (Ollama and llama.cpp are recommended for local inference).

Linux desktop builds

Tauri needs GTK/WebKit dev libraries. On Debian/Ubuntu:

Terminal window
sudo apt install libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1-dev \
  build-essential curl wget file pkg-config libxdo-dev libssl-dev \
  libayatana-appindicator3-dev librsvg2-dev libsoup-3.0-dev

For other distributions, use the upstream Tauri Linux prerequisites. make doctor checks for these on Linux.

Bootstrap

  1. Clone and install.

    Terminal window
    git clone https://github.com/thunderbird/thunderbolt.git
    cd thunderbolt
    make setup

    make setup installs frontend and backend dependencies, optionally installs sccache, and wires up the Claude Code agent symlinks.

  2. Create .env files.

    Terminal window
    cp .env.example .env
    cp backend/.env.example backend/.env
    make doctor

    make doctor generates a BETTER_AUTH_SECRET for backend/.env automatically if it’s empty or still set to the placeholder. Add at least one AI provider key (e.g. ANTHROPIC_API_KEY) — see Configuration for the full list. Root .env is for the Vite/Tauri frontend; backend/.env is for the API server.

  3. Start Postgres + PowerSync.

    Terminal window
    make up

    This runs docker compose -f powersync-service/docker-compose.yml up -d. PowerSync listens on :8080, Postgres on :5433 (the non-default port avoids clashing with a local Postgres). Verify with make status.

  4. Run the dev servers.

    Browser (recommended):

    Terminal window
    make run

    Backend starts on http://localhost:8000, frontend on http://localhost:1420.

    Desktop (Tauri): bun tauri:dev:desktop

    iOS simulator: bun tauri:dev:ios

    Android emulator: bun tauri:dev:android

  5. Sign in. Open http://localhost:1420, create an account, and send a message. If it works, you’re good.

Common Issues

  • make up port conflict — something is bound to 5433 or 8080. Stop it or edit powersync-service/docker-compose.yml.
  • make up fails with a Postgres data-format error — the Postgres image was bumped to v18, which changed its on-disk layout. If your local volume was created with an older version, run make nuke to wipe it and re-init (you’ll lose any local DB state).
  • Backend errors with BETTER_AUTH_SECRET — run make doctor; it generates one for you. Or set it manually with openssl rand -base64 32.
  • powersyncJwtSecret must be at least 32 characters — set POWERSYNC_JWT_SECRET in backend/.env to match the one baked into powersync-service/config/config.yaml.
  • Playwright on Ubuntu 26.04 ARM64 — make setup automatically uses Playwright’s Ubuntu 24.04 ARM64 browser build until Playwright supports 26.04 directly.
  • Tests behave weirdly — fake timers are globally installed; see testing.md.

Helpful Makefile Targets

Command What it does
make doctor Verifies your tools + env files. make doctor-q only prints issues.
make run / make dev Starts backend + frontend. Kills stale processes on :8000 and :1420 first.
make up Starts PowerSync and Postgres.
make down Stops containers, keeps volumes.
make nuke Wipes all container data and rebuilds from scratch.
make check Runs type-check, lint, and format-check.
make format Formats frontend, backend, and Rust.

Next Steps