Configuration reference

With Docker, settings go in a .env file next to docker-compose.yml. Start from the template:

cp .env.example .env

Apply changes with docker compose up -d. Nothing is required: every setting has a working default.

Where a setting can come from, later sources override earlier ones:

1. state/secrets.env: generated on first start. Holds BOT_TOKEN and BOOTSTRAP_CODE.
2. .dev.vars: only if you mount one into the container (older setups did this).
3. .env / container environment variables.

Running without Docker (npm run serve)? Put the same settings in .dev.vars instead. See .dev.vars.example.

Docker

Security

Response headers

Every response carries these, with no configuration:

Content-Security-Policy

Left off by default. A policy that does not match your setup breaks voice, uploads or themes silently — the browser blocks the request and the app just stops working — so it is opt-in rather than on by default.

HUDDLE_CSP=1

Then check, in this order, before leaving it on: join a voice room, upload an image and a PDF, apply a custom theme, send a voice message, open a link preview, and start the music bot. If any of those break, either leave the CSP off or write your own with HUDDLE_CSP_POLICY.

The bundled policy allows blob: (the dice renderer, the noise-suppression worklet and the session recorder all run from blob URLs), 'wasm-unsafe-eval' (MediaPipe selfie segmentation), 'unsafe-inline' for styles (themes inject CSS), and ws:/wss: for the realtime socket and LiveKit. Tightening it means checking those features still work.

Rate limiting

Built in, no configuration. Fixed windows, counted in the database so they hold across restarts and worker isolates:

Per-username login limiting means one attacker cannot lock you out by hammering your name, and a botnet cannot avoid the IP limit by rotating for a single account. Both buckets must have room for a login to proceed. Exceeding a budget returns 429 with a Retry-After header.

Behind a reverse proxy, the client address comes from CF-Connecting-IP, then the first hop of X-Forwarded-For, then X-Real-IP. If none is present every request shares one bucket — it fails closed (over-limiting) rather than open, so make sure your proxy sets one of those headers.

Web address

Voice and video

Push notifications

Lets Hoffle notify people about DMs and mentions while the tab is closed. Generate a key pair once:

docker compose exec hoffle npx web-push generate-vapid-keys

Do not change the keys later, or existing subscriptions stop working.

Native Android app notifications (Firebase)

The Android app in mobile/ gets notifications through Firebase Cloud Messaging, since browser push can't run inside the app.

The matching google-services.json goes into the app build; see mobile/README.md. iOS isn't covered: a sideloaded app can't receive Apple push notifications.

Phone notifications without vendor keys (ntfy / UnifiedPush)

Each user can paste an ntfy topic URL under Settings → Appearance → Phone notifications. Hoffle then POSTs mentions, DMs, event reminders and incoming calls (high priority) to that topic, and the ntfy app delivers them in the background on Android and iOS. Nothing here needs VAPID, APNs or FCM credentials. Run your own ntfy server if you'd rather not use ntfy.sh.

Integrations

Internal service addresses

Docker Compose sets these for you. You only need them when running services by hand.

Advanced

Adding a new setting (for developers)

Wrangler does not pass the container's environment through to the worker. scripts/entrypoint.sh copies an explicit list of variables (PASSTHROUGH_KEYS) into the env file the worker reads. If you add a binding that should be configurable from .env, add its name to that list.