Operations

This section covers day-two concerns: keeping your instance safe, upgrading it, and diagnosing problems.

Fast links

Publish the docs site to Cloudflare Pages
hiveloom backup create before every upgrade
hiveloom health after every restart
hiveloom logs and journalctl -u hiveloom -f when something feels off

Backup & restore


hiveloom backup create --output /var/backups/hiveloom-$(date +%F).tar.gz
hiveloom backup list
hiveloom backup restore --input /var/backups/hiveloom-2026-04-17.tar.gz

The backup archive contains every tenant database, the platform database, and the encryption master key. Store the archive somewhere off the VPS.

Upgrade

hiveloom backup create ... — always back up first.
sudo systemctl stop hiveloom.
Replace /usr/local/bin/hiveloom with the new binary.
sudo systemctl start hiveloom.
hiveloom health to verify.

Schema migrations run automatically on startup. If an upgrade fails, the previous binary + backup restore gets you back to the prior version.

Troubleshooting

Symptom	Most common cause
`healthz` returns 503	LLM provider credential rejected. Rotate it.
OAuth metadata shows `http://` URLs over HTTPS	Reverse proxy not forwarding `X-Forwarded-Proto: https`.
`caddy: context deadline exceeded`	Cloud provider blocks port 80 at the edge.
MCP client shows no tools	Wrong tenant/agent slug in the MCP URL.
Agent replies are empty	Token budget exhausted; inspect `hiveloom compaction-log`.

If you are publishing this docs site itself, use Cloudflare Pages deployment.