Upgrade (Linux) · Halton Meter docs

Upgrade the Halton Meter daemon in place on Linux — pipx upgrade, systemd-unit regeneration, and what survives the bump. Public beta.

Halton Meter ships as a single PyPI package, halton-meter. Upgrading on Linux is a package swap plus a halton-meter init to regenerate the systemd units pointing at the new binary path. The edge unit stays bound to port 8081 through the whole sequence, so apps with HTTPS_PROXY already in their environ keep working in pure-passthrough mode while the daemon swaps under them.

The upgrade sequence

Pick the channel you installed with:

~ — uvx (canonical, ephemeral)

$ halton-meter --version                                # before
$ uv cache clean halton-meter                        # force a fresh fetch
$ uvx halton-meter --version                         # picks up the latest wheel
$ halton-meter init --apps --non-interactive            # regenerate units
$ halton-meter status                                  # confirm

~ — uv tool (persistent on PATH)

$ halton-meter --version                                # before
$ uv tool upgrade halton-meter                       # in-place upgrade
$ halton-meter init --apps --non-interactive            # regenerate units
$ halton-meter status                                  # confirm

~ — pipx

$ halton-meter --version                                # before
$ pipx upgrade halton-meter                            # in-place upgrade
$ halton-meter init --apps --non-interactive            # regenerate units
$ halton-meter status                                  # confirm

The second init is required because the systemd units embed the absolute path to the halton-meter binary in their ExecStart=. pipx upgrade may or may not change that path; re-running init regenerates the units and reloads systemd.

init is idempotent — running it twice does no harm. The cert is detected as already trusted, the certifi marker is detected, the existing units are diffed against the regenerated ones, and the daemon is restarted only if something actually changed.

What survives an upgrade

Surface	Survives?
`~/.halton-meter/db.sqlite`	Yes — your captured data
`~/.halton-meter/config.toml`	Yes
`~/.halton-meter/effective-ports.json`	Yes (re-validated by `init`)
`~/.mitmproxy/mitmproxy-ca-cert.pem`	Yes — same CA
`loginctl enable-linger` setting	Yes
certifi patch in the pipx venv	Re-validated; re-applied if `pipx upgrade` rebuilt the venv
Shell rc env-var block	Yes — Halton Meter does not write these on Linux, so they’re untouched
systemd unit files	Regenerated and reloaded

Your captured cost data is never touched on upgrade. SQLite schema changes (if any) run as _migrations on first connect.

Channel summary

Channel	First install	Upgrade
`uvx` (canonical, ephemeral)	`uvx halton-meter init --apps --non-interactive`	`uv cache clean halton-meter && uvx halton-meter --version`
`uv tool` (persistent on PATH)	`uv tool install halton-meter`	`uv tool upgrade halton-meter`
`pipx`	`pipx install halton-meter`	`pipx upgrade halton-meter`
`pip` (in a venv)	`pip install halton-meter`	`pip install --upgrade halton-meter`

After any of the above, run halton-meter init --apps --non-interactive to regenerate units. Then verify:

halton-meter status

Watch the swap in real time

If you want to see the edge stay up while the daemon cycles:

~ — observe the upgrade

$ systemctl --user is-active halton-meter.service halton-meter-edge.service
active
active
$ journalctl --user -u halton-meter.service -f &       # watch daemon swap
$ pipx upgrade halton-meter
$ halton-meter init --apps --non-interactive
# edge unit stays Active=active throughout; daemon shows
# daemon.exit then daemon.startup.ready a few seconds later

What if the new daemon won’t start

Roll back to the previous version and file an issue:

~ — pin a previous version

$ pipx install --force halton-meter==0.1.22.24
$ halton-meter init --apps --non-interactive
$ halton-meter status

If the daemon enters a restart loop (systemd’s start-limit-hit), clear the burst counter and re-init clean:

systemctl --user reset-failed halton-meter.service halton-meter-edge.service

halton-meter init --apps --clean

Then file an issue at operator@haltonlabs.com with [linux-beta] in the subject and include halton-meter doctor --json output plus the relevant journalctl --user -u halton-meter.service excerpt.

What’s next

Troubleshooting — diagnostic tree when an upgrade leaves something broken
Logs — where post-upgrade structured events land