Test locally

Run a Breeze Buddy backend on your laptop, skip KMS, use Daily test mode, and iterate on templates without touching production.

You can run the full backend locally against a real Daily.co room — no telephony provider, no KMS, no cloud recording. Iteration loops drop from “push-and-wait” to “edit template JSON, dial Daily, listen”.

Steps

1. Clone and bootstrap

git clone <clairvoyance-repo>
cd clairvoyance
./scripts/setup.sh
uv run python -m scripts.create_tables create

2. Minimum env

Create a .env file with the smallest set of variables that works:

SKIP_KMS_DECRYPT=true
#
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=breeze
POSTGRES_PASSWORD=breeze
POSTGRES_DB=breeze
#
REDIS_HOST=localhost
REDIS_PORT=6379
#
# Voice pipeline
DEEPGRAM_API_KEY=...
ELEVENLABS_API_KEY=...
ELEVENLABS_VOICE_ID=...
#
# Daily
DAILY_API_KEY=...
DAILY_API_URL=https://api.daily.co
#
# Pools — keep small locally
VOICE_AGENT_POOL_SIZE=1
DAILY_ROOM_POOL_SIZE=2
#
# Skip things you don't have
UPLOAD_BREEZE_BUDDY_CALL_RECORDINGS_TO_CLOUD=false
SLACK_ALERTS_ENABLED=false
ENABLE_SCORE_MONITORING_LOOP=false

SKIP_KMS_DECRYPT=true lets you insert plaintext credentials directly into Postgres instead of KMS-encrypted blobs — critical for local.

3. Run

uv run python run.py

The server listens on its configured port (default 8000 unless overridden). Health check: curl localhost:8000/health.

4. Push a test lead

Use execution_mode: "DAILY_TEST" to route the call to a Daily room you open in your browser:

curl -X POST localhost:8000/agent/voice/breeze-buddy/leads \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "request_id": "local-1",
    "template": "my-first-template",
    "execution_mode": "DAILY_TEST",
    "payload": {
      "customer_mobile_number": "+14155551234",
      "customer_name": "Local Tester"
    }
  }'

Then POST to /agent/voice/breeze-buddy/connect with the returned lead_call_tracker_id and open room_url in a browser.

What you can’t test locally

• Telephony providers — Twilio, Plivo, Exotel require public webhook URLs. Use ngrok or Cloudflare Tunnel if you need to test, but it’s often easier to test these flows in staging.
• Langfuse auto-eval — the alerting loop depends on a shared Langfuse + Redis. Point at a shared dev Langfuse if needed; otherwise leave it disabled.
• Warm transfer to real human — uses provider bridging. Test the function-call path via traces; test the full bridge in staging.