systemd

With Caddy sitting in front, Hiveloom should bind to loopback only. The public internet reaches Hiveloom through Caddy, not directly.

1. Create the service user (if not already)


sudo useradd --system --home-dir /var/lib/hiveloom --shell /usr/sbin/nologin hiveloom
sudo mkdir -p /var/lib/hiveloom
sudo chown hiveloom:hiveloom /var/lib/hiveloom

2. Write the unit file

Save as /etc/systemd/system/hiveloom.service:


[Unit]
Description=Hiveloom service
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
User=hiveloom
Group=hiveloom
ExecStart=/usr/local/bin/hiveloom serve --host 127.0.0.1 --port 3000 --data-dir /var/lib/hiveloom
Restart=on-failure
RestartSec=5
Environment=HIVELOOM_DATA_DIR=/var/lib/hiveloom
 
# Hardening (optional but recommended)
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/hiveloom
PrivateTmp=yes
 
[Install]
WantedBy=multi-user.target

Note the --host 127.0.0.1 flag: Hiveloom listens on loopback only. Caddy proxies from there.

If you installed Hiveloom with the one-line installer on Linux, you already have a hiveloom.service unit. In that case, verify the current ExecStart line before replacing anything:


sudo systemctl cat hiveloom

The installer-generated unit already binds to 127.0.0.1 by default because hiveloom serve defaults to --host 127.0.0.1.

3. Enable and start


sudo systemctl daemon-reload
sudo systemctl enable --now hiveloom
sudo systemctl status hiveloom

Verify it’s bound to loopback and not the public interface:


ss -tlnp | grep :3000
# Must show "127.0.0.1:3000", not "0.0.0.0:3000"

4. End-to-end smoke test


# Health over HTTPS — hits Caddy, Caddy hits Hiveloom on loopback
curl -s https://hiveloom.example.com/healthz
# {"status":"ok"}
 
# Metadata — URLs must be https://
curl -s https://hiveloom.example.com/.well-known/oauth-authorization-server | jq .issuer
# "https://hiveloom.example.com"

If both succeed, your VPS deployment is done. Time to create your first agent.

Logs

Systemd captures Hiveloom’s stderr/stdout:


sudo journalctl -u hiveloom -f        # follow live
sudo journalctl -u hiveloom --since "10 min ago"

Hiveloom also writes its own structured logs — see hiveloom logs.

Upgrading the binary

Stop the service, replace the binary, restart:


sudo systemctl stop hiveloom
sudo cp /path/to/new/hiveloom /usr/local/bin/hiveloom
sudo systemctl start hiveloom
sudo systemctl status hiveloom

For a more thorough upgrade path (backups, migration, rollback), see Operations.

Next: Create your first agent.