CLI reference · 02 macOS only

halton-meter start

Bootstrap the Halton Meter daemon and watchdog into launchd. The edge stays up across every start/stop cycle so your tools are never disrupted.

macOS 12+ · Python 3.11+ Reading time 2 min Updated May 11, 2026

halton-meter start boots the daemon and watchdog plists into the user’s launchd domain. The edge process is independent — it was loaded by halton-meter init with KeepAlive=true, and it survives every start / stop / crash cycle so your tools’ user-facing port 8081 stays bound regardless of daemon state.

For the architecture, see Fail-open behaviour.

Synopsis

halton-meter start [--quiet]

What it actually does

  1. launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.haltonlabs.meter.plist
  2. launchctl bootstrap for com.haltonlabs.meter.watchdog similarly
  3. launchctl kickstart to force-start (the modern verbs — the deprecated load -w is not used anywhere in lifecycle/_macos.py)
  4. Wait up to 30 seconds for the daemon’s /health to return 200, retrying every 500ms

The edge is not touched. If halton-meter init ran, the edge is already loaded with RunAtLoad=true + KeepAlive=true and is bound to port 8081.

Flags

FlagPurpose
--quietOne-line status, suitable for shell-rc helpers and scripts. Default output is a Rich-formatted panel.

Typical run

~ — halton-meter start 
$ halton-meter start
✓  daemon registered    com.haltonlabs.meter
✓  watchdog registered  com.haltonlabs.meter.watchdog
✓  daemon healthy       api: 127.0.0.1:8765  edge: 127.0.0.1:8081 (already up)
$ halton-meter status

Quiet mode for shell helpers

~/.zshrc — auto-start helper 
# Halton Meter — start daemon if not running
halton-meter start --quiet 2>/dev/null

There is no restart subcommand

The classic stop-then-start sequence is the canonical restart:

halton-meter stop && halton-meter start

The daemon plist deliberately omits KeepAlive (since v0.1.21.1 — any KeepAlive value silently sets RunAtLoad=true, which we do not want), so a daemon crash will not auto-revive. Fail-open is preserved by the always-on edge; the user runs halton-meter start again when they want metering back.

Troubleshooting startup

If start returns but status shows the daemon down, the failure is almost always one of three things:

  1. Stale launchctl HTTPS_PROXY causing the daemon to proxy itself. See Stale launchctl env.
  2. Port conflict on 8090 or 8765 — port_alloc.py will renegotiate, but if every fallback is taken the daemon exits. halton-meter status shows the chosen tuple; effective-ports.json confirms it.
  3. Cold-boot transient rc=5 (“Input/output error”) that macOS surfaces during first-after-boot init of KeepAlive jobs. The bootstrap loop retries on an exponential schedule. After exhaustion the failure is appended to a post-mortem file under ~/.halton-meter/.
halton-meter doctor

is the comprehensive next step.

What’s next