A previous release had provenance metadata, but this release does not. View details.
Halton Meter
Local LLM API proxy. Observes outbound traffic, attributes every request to a project, computes exact cost, surfaces it via terminal reports and a loopback HTTP API.
Designed for solo developers, agencies, and in-house dev teams who use Claude Code, the Anthropic SDK, OpenAI, Gemini, xAI, or other LLM clients heavily and want transparency over what's being spent and on what.
Platform support
macOS is the primary supported platform. Install + lifecycle + capture + reporting are exercised end-to-end on the maintainer's daily-driver before every release.
Linux is in public beta as of v0.1.24. Verified on Ubuntu 24.04 LTS against (a) a Docker + systemd-container soak run on every commit and (b) an AWS Lightsail instance with real systemd-logind, real loginctl enable-linger, real reboot survival, real Claude Code sessions captured end-to-end (Anthropic + Gemini interception confirmed). Other distros (Debian, Fedora, Arch) should work — same systemd --user mechanism — but are not yet covered by the release gate. Please open an issue with [linux-beta] in the subject if you hit anything; we want to graduate Linux to "primary supported" with broader distro coverage in v0.2.
Linux runs apps-mode only (env-var-only HTTPS_PROXY — no system-level proxy via networksetup-equivalent or transparent-proxy via iptables / nftables; that scope is on the post-v1.0 roadmap). The daemon + edge ship as systemd --user units under ~/.config/systemd/user/; the watchdog unit is macOS-only (the launchd-based networksetup poller has no Linux counterpart). See LINUX.md for the full Linux setup guide.
Windows apps-mode is available as of v0.2.11 (beta). uvx halton-meter works on Windows 10 / 11. No admin rights required for apps-mode. The daemon and edge run as Task Scheduler user-level tasks; the mitmproxy CA cert is installed into the user cert store via certutil -user -addstore Root; the system proxy is written to HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings with a WM_SETTINGCHANGE broadcast so Electron apps (Claude Code, VS Code) pick it up without restart. Full-mode (machine-wide proxy, NSSM service, MDM cert deployment) is on the post-v1.0 roadmap. See INSTALL.md for Windows setup instructions.
Quick install
Prerequisites
| Requirement | Notes |
|---|---|
uv |
Install with curl -LsSf https://astral.sh/uv/install.sh | sh (macOS / Linux) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows). uv ships its own Python interpreter, so you do not need to install Python yourself. |
| macOS or Linux | macOS (any recent version) — primary support. Linux with systemd --user and loginctl enable-linger — public beta. Windows: distribution layer works, OS-level proxy install is future work. |
| Admin password (one-time) | Granted during init to install the mitmproxy CA cert into the macOS System keychain. |
Everything else (mitmproxy, FastAPI, SQLAlchemy, structlog, Rich, Click, certifi) is bundled in the wheel. No Docker, no Postgres, no separate backend.
Install
Pick one — they all install from the same PyPI wheel:
# Option A — uvx (canonical; zero Python prereq, no PATH change).
uvx halton-meter --version
# Option B — uv tool install (persistent; puts `halton-meter` on PATH).
uv tool install halton-meter
halton-meter --version
# Option C — pipx, if you already use it.
pipx install halton-meter
halton-meter --version
Then run the setup flow (substitute uvx halton-meter for halton-meter if you chose Option A):
# one-time setup: cert trust + launchd supervisors + per-shell env block
halton-meter init --apps
# start metering
halton-meter start
# verify health
halton-meter status
After this, every terminal you open and every Spotlight-launched app routes its LLM API traffic through the meter. Existing terminals get the env on next shell open.
To stop metering: halton-meter stop. To remove entirely: halton-meter uninstall.
Graceful uninstall.
uninstallstops metering and removes the launchd supervisor plists, but the edge process keeps running in pure-passthrough mode until next reboot. This is intentional — apps withHTTPS_PROXY=http://127.0.0.1:8081baked into their environment (running terminals, IDEs, browsers) don't lose connectivity mid-flow. On reboot the edge dies with your session and isn't respawned. To kill it immediately:pkill -f "halton-meter edge". To also wipe~/.halton-meter/db.sqliteand logs, add--purge.
What it does
Captures and costs every outbound LLM API call across these providers:
- Anthropic —
api.anthropic.com(/v1/messages, streaming + non-streaming, extended thinking, cache read/write) - OpenAI —
api.openai.com(/v1/chat/completions,/v1/responses,/v1/embeddings; o-series reasoning tokens; prompt cache reads) - Gemini —
generativelanguage.googleapis.com(/v1beta/models/<model>:generateContent,:streamGenerateContent,:embedContent,:batchEmbedContents; Gemini 2.5 thinking tokens; >200k tiered pricing; cached-content reads) - xAI —
api.x.ai(/v1/chat/completionsOpenAI-compat shape;/v1/messagesAnthropic-compat shape)
Project attribution via HALTON_PROJECT env var, a .haltonrc file in the working directory, or the working directory name. macOS GUI apps get attributed via launchctl bundle-ID humanisation (mac:com.docker.docker → Docker).
Storage — local SQLite (~/.halton-meter/db.sqlite) with WAL. Token counts, latency, cost in integer millicents (no float drift), and full request/response bodies with credential redaction. Body capture default ON; opt out per project with halton-meter project <slug> set body-capture off. Background retention sweep keeps disk bounded (default 90 days).
Loopback HTTP API at 127.0.0.1:8765 for the cloud dashboard or any reader. JSON in, JSON out. Audit trail of every request, policy event, and reconciliation run.
Cost report — single-command client-billing surface:
halton-meter report # default window
halton-meter report --since 7d # last 7 days
halton-meter report --from 2026-04-01 --to 2026-05-01
halton-meter report --vs-previous # Δ% vs prior period per row
halton-meter report --by project # filter to one breakdown
halton-meter report --csv > spend.csv # export
halton-meter report --json | jq # pipe to dashboard
Layout adapts to terminal width (60 / 80 / 100 / 120 cols). Includes share-of-spend bars, p95 latency, and per-project 7-day trend sparklines.
Failure mode — if the daemon is stopped, upgraded, or crashes, the always-on edge process transparently tunnels traffic direct to upstream. Your apps never see ConnectionRefused. Logging is observation infrastructure, never a single point of failure.
Pricing rates
Halton Meter ships with a bundled per-model pricing matrix sourced from each provider's public price page. Every captured request is costed against this matrix at write time and the rate-source is stamped on the row (requests.rates_source = "bundled-YYYY-MM-DD" or "override"), so every figure in a report or CSV export is traceable to a specific snapshot.
Three layers of freshness defence:
- Visible.
halton-meter reportprintsRates: bundled YYYY-MM-DD · N override(s)under the masthead. - Overridable.
halton-meter pricing set / list / resetrecords operator-set rates. Future captures use them immediately; historicalhalton-meter recompute-costsconsults overrides first. - Probed.
halton-meter doctordoes a 2s loopback fetch ofrates-manifest.jsonand warns if the bundled date trails the latest published bundle. Fail-open: any network/parse error leaves the check silent. Disable withHALTON_METER_NO_RATES_PROBE=1.
Cost math itself never touches the network. The freshness probe is an opt-out signal — it never affects pricing, only the doctor row.
Three install modes
| Mode | Invoke | What's metered | Risk |
|---|---|---|---|
| env-var-only (default) | halton-meter init |
Whatever you explicitly route via halton-meter run <cmd> (Claude Code, the Anthropic SDK, python my_script.py, an interactive subshell with --shell, …). |
None — never touches the system proxy. |
| apps | halton-meter init --apps |
Spotlight/Dock-spawned apps that respect HTTPS_PROXY env (Claude Desktop, JetBrains IDEs, Cursor, Windsurf), and new shells launched after the install. Not browsers. |
None — system proxy still untouched. |
| full | halton-meter init --full |
All of apps plus browsers and GUI apps that ignore HTTPS_PROXY env (every other client) via the macOS system proxy. |
May break HSTS browser sites if the CA isn't trusted by SecTrust. The daemon refuses to enable the proxy when cert verification fails. |
Switching modes is one command — the install path reconciles all mode-specific state in either direction. No uninstall step required.
Decision tree
- "I just want to meter my Claude Code / SDK calls." →
init(env-only default) - "I want every app I open from Spotlight metered, but I don't want my browser to break." →
init --apps - "I want every HTTPS request my Mac makes, including browser traffic." →
init --full
Branded CLI surfaces
Every user-facing command renders with the brand-orange Halton Meter mark and editorial sections:
halton-meter status— aggregate verdict (HEALTHY / DEGRADED / BROKEN), Component Health table with pill state indicators, ground-truth port resolution, sentinel state.halton-meter doctor— row-by-row diagnostic with pill severity and copy-pasteable next-actions.halton-meter report— masthead with date range, summary KV block, by-project + by-model tables with share-of-spend bars and 7-day sparklines.halton-meter init / uninstall— sectioned step rows (supervisor (launchd)/certificate trust/shell environment), idempotency-aware.halton-meter start / stop— masthead + step panel with PIDs and/healthlatency.
Layouts adapt to terminal width. The aggregate verdict is always honest — never says HEALTHY when truth disagrees.
Useful commands
halton-meter init [--apps|--full] [--no-shell-rc] # install (re-runnable; idempotent)
halton-meter start | stop # supervisor control
halton-meter status [--json] # mode-aware HEALTHY / DEGRADED / BROKEN
halton-meter doctor [--json] [--curl] # detailed diagnostics
halton-meter report [--since 7d | --from … --to …] # cost report (see above)
halton-meter run <cmd> [args...] # exec wrapper that injects metering env
halton-meter run --shell # interactive subshell with metering env
halton-meter project <slug> set body-capture off # opt out of body capture per project
halton-meter bodies show <request_id> # inspect a captured body
halton-meter bodies stats # body-capture disk usage
halton-meter uninstall [--purge] # remove (graceful — see above)
halton-meter reset-proxy # emergency: disable system proxy
halton-meter version | --version # version
halton-meter doctor is the diagnostic of last resort: it prints every signal that matters (daemon health, cert trust, system proxy state, launchctl env, shell rc marker, env in current process) and ends with a top-line verdict and concrete next-actions. --curl adds an end-to-end TLS smoke test against https://example.com (hard-coded — never a provider domain).
Architecture (edge ↔ daemon split)
┌────────────────┐ ┌─────────────────────────┐
│ apps │ │ halton-meter-edge │
│ (Claude Code, │ ─CONNECT──► always-on TCP proxy │
│ SDKs, ...) │ │ listens on :8081 │
│ HTTPS_PROXY=...│ └────────┬─────────┬──────┘
└────────────────┘ │ │
healthy? not healthy
│ │
▼ ▼
┌────────────────┐ ┌─────────────────┐
│ halton-meter │ │ upstream API │
│ daemon │ │ (direct tunnel,│
│ │ │ no metering) │
│ mitmproxy + │ └─────────────────┘
│ FastAPI + │
│ SQLite │
└────────────────┘
Three macOS LaunchAgents:
com.haltonlabs.meter.edge— always-on TCP CONNECT proxy on:8081. Apps see this inHTTPS_PROXY. When the daemon is healthy, chains CONNECTs to it for full metering. When the daemon is down, tunnels direct.com.haltonlabs.meter— daemon (mitmproxy + FastAPI + SQLite) on:8090internal +:8765API.com.haltonlabs.meter.watchdog— Layer-2 watchdog. Polls/healthevery 1.5s; disables the system proxy after ~7.5s of unresponsiveness so traffic flows direct.
halton-meter stop no longer breaks running apps. They keep working in passthrough until you halton-meter start again. halton-meter uninstall drops the supervisor plists; the edge keeps running in passthrough until reboot or manual pkill.
What it doesn't do
- Doesn't wrap SDKs — your code stays exactly as it is
- Doesn't intercept anything you don't ask it to — only configured LLM endpoints
- Doesn't send your data anywhere by default — runs entirely locally
- Doesn't break your workflow — if the proxy fails, traffic falls through to the real provider
Known limitations
Honest list, not a roadmap. Apps that ignore both the macOS system proxy AND HTTPS_PROXY env have no general capture path:
- Go binaries with
GODEBUG=netdns=go. Go's pure-Go resolver path bypassesHTTPS_PROXYenv in some builds. Calls reach the provider unmetered. - libcurl callers using
--insecureor withCURLOPT_PROXYnot honoured.--insecurecallers skip TLS verification entirely. - WSL2 networking on Windows hosts. Currently doesn't route WSL2 guest traffic through the Windows-side proxy. Linux-native and macOS are the supported platforms.
- Hardcoded HTTP stacks that open raw TLS sockets to known provider IPs. Anything that bypasses both system proxy AND
HTTPS_PROXYenv will reach the provider unmetered. - Late-coming network interfaces. macOS network services are enumerated once when the daemon starts. If you plug in a new interface (Thunderbolt dock, USB-tethered iPhone), restart with
halton-meter stop && halton-meter start.
Project
Halton Meter is source-available under the Polyform Perimeter License 1.0.1. Built by Halton Labs.
- Website: https://haltonmeter.com
- Contact / support / bug reports: operator@haltonlabs.com
- Security disclosures: operator@haltonlabs.com (subject prefix
[security]) — please do not post to public channels - Source: available on request — email operator@haltonlabs.com with your use case
This package is the daemon component — the local proxy that intercepts, attributes, and costs LLM API traffic. The cloud dashboard and Phase 3 multi-tenant SaaS are developed separately.
Metadata
Release files for halton-meter 0.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Loss of provenance
These files do not have provenance metadata, despite files in a prior release including this data.
We recommend further investigation before installing these files. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| halton_meter-0.6.2.tar.gz | 1.4 MB | Without provenance | Details for halton_meter-0.6.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| halton_meter-0.6.2-py3-none-any.whl | Python 3 | none | any | Details for halton_meter-0.6.2-py3-none-any.whl |
Total release size: 2.2 MB
Release files / halton_meter-0.6.2.tar.gz
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | halton_meter-0.6.2.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a7cd4047c13a6d1d25b73fcdda10121edc472ec0ac03e8ce4110e8f7d8e2264a
|
|
BLAKE2b-256 checksum How to use checksums |
7de18a35350ba98d0e8f4fadbe80b7d25a567c7a9e460febc5c8bdf754087960
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.13
|
Release files / halton_meter-0.6.2-py3-none-any.whl
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | halton_meter-0.6.2-py3-none-any.whl |
|---|---|
| Size | 849.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1acc5c2a84d9e73f0033d4c099e550f01c16a97a3b770f5a36e061c70bc7532a
|
|
BLAKE2b-256 checksum How to use checksums |
4774e028af87b6d8f46cbbb142385c502a76af98704a6c318fdf5cd4edd3c755
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.13
|
Security for halton-meter 0.6.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Loss of provenance
A previous release of these files had provenance metadata, but this release does not.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Release comparison
- Removed 0.6.0 2 files With provenance
- Added 0.6.2 2 files Without provenance
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.