Skip to Content
Deploy on a VPSDeploy on a VPS

Deploy on a VPS

This page is the recipe for taking a plain hiveloom serve on a VPS and turning it into a production-ish deployment that:

  • is reachable over https://<your-host> with an automatically-renewed Let’s Encrypt cert,
  • does not expose its admin / MCP port on the public internet, and
  • only keeps the ports open that are actually needed.

Choose the right path

Use this page if you want:

  • your own reverse proxy on the VPS,
  • direct control over TLS termination,
  • no Cloudflare dependency in the request path.

Use Cloudflare Tunnel instead if your main goal is “give Claude/Cursor/remote MCP clients an HTTPS URL quickly” without opening ports 80 and 443 to the internet.

Hiveloom does not install anything for you. The one thing Hiveloom provides is a CLI command that prints a ready-to-use Caddyfile for your hostname — the rest is on you (install Caddy, point your DNS, apply firewall rules). The recipe below is the short version.

What Hiveloom contributes

hiveloom tls render --host hiveloom.example.com --email you@example.com

Prints a Caddyfile to stdout. That is the entire built-in tooling for this feature. Pipe it where you want it:

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

Everything else below is operator action.

The five steps

  1. Point your DNS at the VPS.
  2. Apply a minimal firewall (SSH + 80 + 443).
  3. Install a reverse proxy — Caddy is the default.
  4. Obtain a TLS certificate via Let’s Encrypt.
  5. Run Hiveloom as a systemd service bound to loopback.

Follow them in order. Each page has the full command set — you don’t need to cross-reference anything.

Smoke test at the end

If everything is wired up correctly, you should see:

curl -s https://hiveloom.example.com/healthz
# {"status":"ok"}
 
curl -s https://hiveloom.example.com/.well-known/oauth-authorization-server | jq .issuer
# "https://hiveloom.example.com"

The OAuth metadata URLs must start with https://. If they start with http://, the reverse proxy isn’t forwarding the right headers — revisit Reverse proxy.

FAQ

Does Hiveloom install Caddy for me? No. It prints the Caddyfile; you install Caddy.

Does Hiveloom check DNS before printing the Caddyfile? No. Run dig +short <host> first.

Why does hiveloom tls render not write the file itself? You asked Hiveloom to stay out of your system configuration. Pipe to tee when you want the file.

InstallCloudflare Tunnel