Fail-open behaviour · Halton Meter docs

The full set of invariants that keep your tools running when Halton Meter's daemon isn't — the edge process, the watchdog, the asymmetric health TTL, and what happens during stop, crash, and uninstall.

A metering proxy that breaks your tools when it crashes is worse than no proxy at all. Halton Meter’s central design rule — [the cardinal “zero workflow disruption” rule] — is that a daemon crash, restart, or upgrade must be invisible to the LLM clients that have its proxy baked into their environ. This page is the full set of invariants that make that true, and where to look when one of them appears to have failed.

For the architectural shape, see Proxy model.

The seven invariants

The edge owns the user-facing port across every daemon transition. com.haltonlabs.meter.edge runs with KeepAlive=true and RunAtLoad=true. Port 8081 stays bound during stop, crash, pipx upgrade, and reinstall.
The edge never decrypts in passthrough mode. A daemon outage triggers raw TCP tunnel mode — 200 Connection Established, bidirectional byte shuttle, no TLS termination, no metering.
A daemon crash does not cause connection failure. It causes the next request to passthrough. Asymmetric /health TTL — 1000ms when healthy, 200ms when unhealthy — keeps the edge from polling a dead daemon hot. On ConnectionRefused the cache is invalidated immediately, so the next request falls through without waiting out the TTL.
halton-meter stop does not stop the edge. It stops the daemon and the watchdog only. Apps with HTTPS_PROXY=http://127.0.0.1:8081 in their environ continue to work in pure-passthrough mode for as long as you leave them stopped.
The watchdog is the L2 safety net. The watchdog polls the daemon’s /health every 1.5 seconds. After five consecutive failures (~7.5s) it disables the macOS system proxy on every active interface, returning the user to direct connectivity. The daemon re-enables it on next start, gated on the proxy-managed sentinel.
halton-meter uninstall --graceful leaves the edge running. Default uninstall (bootout of com.haltonlabs.meter.edge) tears it down, which will break already-running apps that have the proxy baked into their environ. --graceful keeps the edge in pure-passthrough mode through the next reboot — long enough for you to restart your tools cleanly.
reset-proxy is the L4 escape hatch. A standalone command that runs networksetup -setsecurewebproxystate <iface> off for every active interface, sentinel-blind and config-independent. Safe to run when nothing is installed. The daemon’s ExitTimeOut=30 shutdown path runs the same routine on launchd-driven exits, so reboot and logout always leave the user’s network connectivity intact.

What “fail-open” rules out

The opposite of fail-open is fail-closed: a metering proxy that blocks requests when it can’t meter them. Helicone is fail-closed by architecture — a Helicone outage stops your tools from reaching the provider. That trade is acceptable for some teams (capture is more important than uptime) and unacceptable for others.

Halton Meter is unconditionally fail-open. There is no toggle to switch this off. If a daemon crash causes you to miss 0.4% of a day’s metered requests, that is the price; your tools never stop.

The asymmetric health-probe TTL

The edge caches its last /health result rather than probing per request. The TTLs:

Last result	TTL	Rationale
Healthy	1000ms	Cheap; daemon is alive, no need to thrash it
Unhealthy	200ms	Fast recovery once the daemon comes back
`ConnectionRefused` raised by `chain`	invalidate immediately	The probe lied; falling through on this same request

The healthy-side TTL is tunable via daemon.edge_health_ttl_ms in config.toml. The unhealthy-side TTL is fixed.

Inspecting fail-open in practice

Stop the daemon and watch the next request still succeed:

~ — confirm passthrough on daemon down

$ halton-meter stop
$ halton-meter run -- curl -sI https://api.anthropic.com | head -1
  HTTP/2 200                          # request still went through (passthrough)
$ halton-meter start
$ halton-meter report --since 5m           # the curl call is NOT in the report — passthrough = no capture

The curl call returned 200. It is not in the report. That is fail-open working as designed.

What goes wrong, and why

If you ever see a request fail with a connection-level error pointing at 127.0.0.1:8081, the edge is the problem, not the daemon:

~ — diagnose edge

$ launchctl print "gui/$(id -u)/com.haltonlabs.meter.edge"
$ tail -n 100 ~/.halton-meter/edge.err.log
$ halton-meter doctor

If the edge plist is missing, re-running halton-meter init regenerates it.

What’s next

Proxy model — the architecture this invariant set is enforced by
Troubleshooting — the diagnostic tree when something does fail