Install Halton Meter on Windows

Halton Meter is a local network proxy that sits between your LLM clients (Claude Code, Cursor, VS Code, Windsurf, the Anthropic SDK, curl) and the LLM provider APIs (Anthropic, OpenAI, Google Gemini, xAI). It intercepts HTTPS via a local mitmproxy instance, parses request and response bodies to extract model name, token counts, and cost, and writes one row per LLM call into a local SQLite database. It never modifies your code or wraps SDKs. If the proxy fails, traffic falls through directly to the provider — your tools keep working. Nothing about your development workflow changes.

Requirements

• Windows 10 or later. Windows 7 and 8 are not supported.
• No admin rights. Apps-mode installs entirely at the current-user level — the registry under HKCU, the Windows user cert store, and a user-level Task Scheduler task.
• uv (recommended) or pipx. uv provisions a matching Python interpreter automatically, so you do not need to install Python yourself.

What ships on Windows today (v0.2.x beta)

Honest scope so you can decide before installing.

If full-mode browser coverage is a deal-breaker, stay on macOS for the v0.2.x line.

Install the package

First install uv (skip if you already have it):

winget install astral-sh.uv

Then pick one of the three install options. All three install from the same PyPI wheel; they differ only in where the binary lives.

A one-shot run with uvx (zero prereqs beyond uv, ephemeral environment):

uvx halton-meter --version

A persistent install that puts halton-meter on your PATH:

uv tool install halton-meter

Or with pipx, if you prefer it:

pipx install halton-meter

uv provisions a matching Python interpreter automatically — you do not need to install Python separately. Confirm the CLI is available:

halton-meter --version

Apps-mode only (v0.2.x)

On Windows, v0.2.x ships apps-mode only. Apps-mode configures proxy and environment settings at the current-user level with no admin rights required:

• Per-user proxy via the Windows registry (HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings). This is the WinINet stack, which Electron apps (Claude Code, VS Code, Cursor, Windsurf), PowerShell, pip, and curl all respect.
• Task Scheduler user-level auto-start task with an ONLOGON trigger. No admin is required for HKCU tasks.
• CA cert into the Windows user cert store via certutil -user -addstore Root. No admin required.
• HTTPS_PROXY / HTTP_PROXY written to HKCU\Environment so new shell sessions inherit the proxy automatically.

Full-mode (machine-wide proxy via HKLM, an NSSM service, and MDM cert distribution) is out of scope for v0.2.x and will raise an error if you try to trigger it.

Run init

> halton-meter init
  1/5  Generating mitmproxy CA certificate…
✓       cert written      %USERPROFILE%\.mitmproxy\mitmproxy-ca-cert.pem
  2/5  Trusting cert in Windows user cert store (no admin)…
✓       certutil -user -addstore Root
  3/5  Setting per-user proxy in the registry (WinINet)…
✓       proxy set         HKCU\…\Internet Settings  127.0.0.1:8081
✓       env written       HKCU\Environment  HTTPS_PROXY HTTP_PROXY
  4/5  Registering Task Scheduler auto-start task (ONLOGON)…
✓       task registered   HaltonMeter (current user)
  5/5  Done.
✓       init complete     mode: apps
!       reopen your terminals so the new env vars load

This generates the CA cert, installs it into your user cert store, sets the registry proxy, writes the proxy env vars to HKCU\Environment, and registers the Task Scheduler auto-start task. After it finishes, reopen any terminals so the new environment variables load.

Verify the install

halton-meter status

Expected output: HEALTHY with all rows green. If any row is amber or red:

halton-meter doctor

doctor prints every diagnostic signal with a concrete next-action for each failure.

Test a capture

Open a new terminal (so the proxy env vars written to HKCU\Environment are loaded) and run any real LLM call. Example with the Claude Code CLI:

claude --print "Reply with exactly: pong"

Then check the report:

halton-meter report

If you see “No captures yet” instead, the most common cause on Windows is an app that was already running before init — see the limitations below.

Known limitations (v0.2.x Windows beta)

• Apps open before init won’t see the new proxy until they are restarted. Quit and reopen Claude Code, Cursor, VS Code, or Windsurf after running init.
• WinHTTP is a separate stack from WinINet. Windows Update and some .NET apps use WinHTTP, which apps-mode does not configure. If you need WinHTTP coverage, run netsh winhttp import proxy source=ie after init.
• Windows is not yet in the GitHub Actions CI matrix. The code paths are unit-tested with a mocked winreg on macOS CI, but there is no end-to-end Windows release gate yet. Treat the beta accordingly and report anything that breaks.

What’s next

1. First request — verify captures are working, understand daily usage, and learn how to switch modes without uninstalling. (Written against macOS; the daemon CLI behaves identically on Windows.)
2. Troubleshooting — diagnoses and fixes for common failure modes: cert errors, daemon issues, and missing captures. (Written against macOS; a Windows-specific guide will follow as the beta matures.)

If you’re stuck for more than five minutes, that’s a docs bug. Email operator@haltonlabs.com with [windows-beta] in the subject and we’ll fix the page, not just answer the question.