Skip to content

HTTPS and a reverse proxy ​

killBottleneck itself speaks plain HTTP. To reach it from outside your LAN, put it behind a VPN or a reverse proxy that terminates TLS. On a local network it is not required — but even there HTTPS unlocks the microphone and connecting AI agents (see below).

Caddy (automatic certificates) ​

# Caddyfile
killbottleneck.your-domain.com {
    encode gzip zstd
    reverse_proxy 127.0.0.1:8090
}

Add Caddy to the stack through docker-compose.override.yml — that file is not overwritten by updates:

yaml
services:
  caddy:
    image: caddy:2
    ports: ["80:80", "443:443"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
volumes:
  caddy_data:

Caddy sends the X-Forwarded-Proto and X-Forwarded-Host headers on its own, so the instance knows it runs on https://… — nothing else to configure.

One line to add to .env: KB_TRUSTED_PROXY_HEADER=X-Forwarded-For. Since v0.97 the instance rate-limits sign-in attempts per client IP (20 / 60 s). Behind a proxy it would otherwise see only the proxy's IP and the whole company would share one bucket. Caddy fills X-Forwarded-For with the real client address itself and never passes on a forged one.

nginx (you obtain the certificate yourself, e.g. with certbot) ​

nginx
server {
    listen 443 ssl http2;
    server_name killbottleneck.your-domain.com;
    ssl_certificate     /etc/letsencrypt/live/killbottleneck.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/killbottleneck.your-domain.com/privkey.pem;

    gzip on;
    gzip_types application/javascript text/css application/json;
    client_max_body_size 50m;          # voice notes, photos and the import of all data (50 MB)

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP         $remote_addr;
    }
}

Three lines without which it "almost works":

  • client_max_body_size — nginx caps request bodies at 1 MB by default and rejects larger ones with a 413. Voice notes and phone photos in the assistant run up to ~4.25 MB (the cap grows with KB_CHAT_MAX_AUDIO_MB / KB_CHAT_MAX_IMG_MB), a JSON map import is 5 MB and the import of all data (My account → My data) is 50 MB. Caddy has no such cap.
  • X-Forwarded-Proto — since v0.79 the instance derives its public address from these headers for the OAuth of AI agents (/mcp) and for the /agent-setup.md guide. Without it the instance announces itself as http:// and clients such as Claude Code refuse OAuth (resource … does not match). The fallback: set KB_PUBLIC_URL=https://killbottleneck.your-domain.com in .env.
  • X-Forwarded-Host — the same for the domain when the proxy runs on another host.
  • X-Forwarded-For + KB_TRUSTED_PROXY_HEADER=X-Forwarded-For in .env — since v0.97 the instance rate-limits sign-in attempts per client IP; without this it sees only the proxy's IP and the whole company shares one bucket. Keep $proxy_add_x_forwarded_for as shown above — the instance reads the last address, the one nginx appended.

Turn compression on — it is a threefold saving ​

killBottleneck does not compress responses itself. There is no way to enable it in PocketBase without changing how the API behaves when it rejects an oversized body, so the job belongs to your proxy.

The main frontend file is (v0.87) roughly 400 kB uncompressed and 120 kB gzipped. On mobile data that is the difference you notice most when opening the app for the first time.

  • Caddy — the encode gzip zstd line above
  • nginx — gzip on; gzip_types … above
  • Cloudflare and similar — happens on its own, nothing to configure

What HTTPS unlocks ​

These things exist only in a secure context, because browsers refuse them over plain HTTP (localhost is the exception):

  • The microphone — voice notes and dictation in the assistant
  • Share… for the My day image — your phone's native share dialog, with no third-party service in the path
  • Adding the app to your phone's home screen — a service worker only runs over HTTPS (in the phone browser: menu → Add to Home screen)
  • Connect AI agent through OAuth — clients only send OAuth credentials to HTTPS or localhost; over http:// on a LAN the guide falls back to an API key (see MCP)
Menu by your name → Connect AI agent. The one-line OAuth route only works on an HTTPS domain — exactly why the proxy is worth finishing.

Neither needs configuring. On an HTTPS domain they simply appear.

Do not forget the redirect URI ​

If you use Google sign-in, the authorized redirect URI in the Google Cloud Console must match the public HTTPS address:

https://killbottleneck.your-domain.com/api/oauth2-redirect

Limits

  • The PocketBase admin UI (/_/) runs over HTTP — behind a proxy either do not expose it (location /_/ { deny all; }) or open it only through an SSH tunnel.
  • Keep the proxy timeout above the AI timeouts (image transcription KB_VISION_TIMEOUT 45 s per attempt; Cloudflare cuts off around 100 s).
  • One domain = one instance. Run a second instance on the same host on a different KB_PORT and KB_NAME and give it its own block in the proxy.

Open source under the MIT license · © Tengo s.r.o.