Skip to Content
Deploy on a VPSReverse proxy

Reverse proxy (Caddy)

Caddy terminates TLS, obtains a free Let’s Encrypt certificate, and proxies traffic to Hiveloom running on localhost. One command to install on Debian/Ubuntu:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

For other distros, see the Caddy install docs .

Confirm:

caddy version              # should print v2.x
systemctl is-active caddy  # should print "active"

Drop in the Hiveloom Caddyfile

Hiveloom ships a helper that prints a ready-to-use Caddyfile for your hostname:

sudo mkdir -p /etc/caddy/Caddyfile.d
hiveloom tls render --host hiveloom.example.com --email you@example.com \
  | sudo tee /etc/caddy/Caddyfile.d/hiveloom.caddy
sudo systemctl reload caddy

Replace hiveloom.example.com and you@example.com. The email is used by Let’s Encrypt for renewal notifications.

The first request to https://hiveloom.example.com/ will trigger Caddy’s ACME flow. Give it 10–30 seconds, then go to TLS to verify.

Bring your own proxy

If you already run Nginx, Traefik, Cloudflare Tunnel, or a Kubernetes ingress, you don’t need Caddy. Point your proxy at Hiveloom bound to 127.0.0.1:3000 (see systemd), and make sure the following forwarded headers are set:

HeaderRequired valueConsumed by
X-Forwarded-ProtohttpsUsed to construct https:// URLs in OAuth metadata.
X-Forwarded-Host<your-public-host>Hostname in public URLs.
Host<your-public-host>Fallback if X-Forwarded-Host is absent.
X-Forwarded-For<client-ip>Optional; logged on the Hiveloom side.

If these are wrong, the OAuth metadata returns http:// URLs and MCP clients reject the auth server.

Minimal Nginx snippet

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name hiveloom.example.com;
 
    # ssl_certificate / ssl_certificate_key — via certbot or your own CA
 
    location / {
        proxy_pass         http://127.0.0.1:3000;
        proxy_set_header   Host                $host;
        proxy_set_header   X-Forwarded-Host    $host;
        proxy_set_header   X-Forwarded-Proto   https;
        proxy_set_header   X-Forwarded-For     $proxy_add_x_forwarded_for;
        proxy_read_timeout 300s;
    }
}

Cloudflare Tunnel

Cloudflare Tunnel can replace Caddy entirely for the public edge. Point the tunnel at http://127.0.0.1:3000 and set httpHostHeader to your public hostname so Hiveloom builds correct OAuth and MCP URLs. Cloudflare forwards X-Forwarded-Proto, and Hiveloom already uses that header when constructing public metadata.

Full working example: Cloudflare Tunnel.

Next: TLS.

FirewallTLS