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:
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)
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 withKB_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.mdguide. Without it the instance announces itself ashttp://and clients such as Claude Code refuse OAuth (resource … does not match). The fallback: setKB_PUBLIC_URL=https://killbottleneck.your-domain.comin.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-Forin.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_foras 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 zstdline 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; overhttp://on a LAN the guide falls back to an API key (see MCP)
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-redirectLimits
- 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_TIMEOUT45 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_PORTandKB_NAMEand give it its own block in the proxy.
Related
- Installation —
docker-compose.override.yml, where Caddy belongs - MCP server — Connect AI agent, OAuth
- Environment variables → Automations —
KB_PUBLIC_URL - Phone — the app on the home screen

