Upgrade · Halton Meter docs

Upgrade the Halton Meter daemon in place — pipx upgrade, plist regeneration, and what survives the bump. The edge keeps your tools running through the swap.

Halton Meter ships as a single PyPI package, halton-meter. Upgrading is a package swap plus a plist regeneration. The edge process stays bound to port 8081 through the whole sequence, so apps with HTTPS_PROXY baked into their environ keep working in pure-passthrough mode while the daemon swaps under them — see Fail-open behaviour.

The upgrade sequence

~ — upgrade in place

$ halton-meter --version                  # before
$ pipx upgrade halton-meter             # bump the binary
$ halton-meter init                       # regenerate plists pointing at the new binary path
$ halton-meter status                     # confirm new version is live

The second init is required because the launchd plists embed the absolute path to the halton-meter binary in their ProgramArguments. pipx upgrade may or may not change that path; re-running init regenerates the plists and bootstraps the new processes.

init is idempotent — running it twice does no harm. The cert is detected as already trusted, the certifi marker is detected, the existing plists 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
`~/.mitmproxy/mitmproxy-ca-cert.pem`	Yes — same CA
Keychain trust	Yes
certifi patch	Re-validated by `init`; re-applied if the bundle changed
Shell rc block	Re-written if the env-var set changed
launchctl user-domain env	Re-applied
launchd plists	Regenerated and bootstrapped

Your captured cost data is never touched on upgrade. To migrate the SQLite schema, the daemon runs _migrations rows on first connect; if a release ships a schema change, it migrates in place on next start.

Other install channels

Channel	Upgrade command
`pipx`	`pipx upgrade halton-meter`
`uv tool`	`uv tool upgrade halton-meter`
`pip` (in a venv)	`pip install --upgrade halton-meter`
`uvx` (one-shot)	Re-run `uvx halton-meter <cmd>`; the latest release is fetched

After any of the above, run halton-meter init to regenerate plists.

What if the new daemon won’t start

Roll back to the previous version and file an issue with halton-meter doctor --json output:

~ — pin a previous version

$ pipx install --force halton-meter==0.1.22.20
$ halton-meter init
$ halton-meter status

If the daemon hangs in the start self-test for the full 30 seconds, Init self-test fails immediately covers the common causes (port held by an old daemon, certifi marker missing on a venv that just bumped Python).

What’s next

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