Upgrading

Upgrading Haloy CLI

Shell Script

To upgrade the Haloy CLI from the previous version:

curl -fsSL https://sh.haloy.dev/install-haloy.sh | sh

The installation script will upgrade your existing installation to the latest version.

Homebrew

If you installed Haloy via Homebrew:

brew upgrade haloy

Javascript Package Managers

If you installed Haloy as a global package:

npm install -g haloy@latest

pnpm add -g haloy@latest

bun add -g haloy@latest

If you installed Haloy as a project dev dependency:

npm install --save-dev haloy@latest

pnpm add -D haloy@latest

bun add -D haloy@latest

Verify Upgrade

Check that the upgrade was successful:

haloy version

Upgrading Haloy on the Server

SSH into your server and run the upgrade script:

curl -fsSL https://sh.haloy.dev/upgrade-server.sh | sh

Note: If you’re not logged in as root, use | sudo sh instead of | sh.

Do not re-run the original install-haloyd.sh script to upgrade. While it won’t overwrite your configuration or data, it will replace your systemd/OpenRC service files, discarding any manual customizations.

This script supports systemd, OpenRC, and SysVinit. On current split-proxy installs, the default upgrade updates haloyd only:

  1. Download the latest haloyd binary
  2. Stop haloyd
  3. Replace the binary
  4. Restart haloyd

haloy-proxy keeps serving application traffic while haloyd is stopped.

First Upgrade From a Pre-Split Install

Older installs ran the proxy inside haloyd. The first upgrade to the split-proxy architecture performs a one-time migration:

  1. Download the latest haloyd and haloy-proxy binaries
  2. Install the haloy-proxy service
  3. Move ports 80 and 443 from haloyd to haloy-proxy
  4. Restart haloyd as the control plane

Expect a brief traffic gap during this one-time migration while the public ports move. If migration fails, the script rolls back the partial proxy install and restores the previous haloyd service.

Future haloyd upgrades do not interrupt traffic.

Upgrading haloy-proxy

Most upgrades only need the default haloyd path. Upgrade the proxy separately when a release specifically changes the proxy, the proxy wire format, or the upgrade output tells you to do it later:

curl -fsSL https://sh.haloy.dev/upgrade-server.sh | sh -s -- --component=proxy

If you already have the script locally, the equivalent command is:

upgrade-server.sh --component=proxy

After a successful one-time migration, the upgrade script prints this reminder: To upgrade the proxy itself later: upgrade-server.sh --component=proxy.

Upgrading haloy-proxy briefly pauses public traffic because the proxy owns ports 80 and 443.

In rare releases the routing snapshot format changes. haloy-proxy rejects snapshots with a newer schema version than it understands and keeps serving its last known routes, so when release notes mention a snapshot schema change, upgrade haloy-proxy first, then haloyd.

Verify Server Upgrade

Check the server versions from your local machine:

haloy server version

Current servers report both components when the proxy is installed:

haloyd version: v0.1.0-beta.66
haloy-proxy version: v0.1.0-beta.66

On the server, you can also check each binary directly:

haloyd version
haloy-proxy version

Stay updated on Haloy

Get notified about new docs, deployment patterns, and Haloy updates.