Runtime governance for self-hosted AI agents, in one binary.
Halo sits between your agent runtime and the model providers (and your MCP servers). Free is the firewall: meter, cap, kill switch, denylist. Cut ($50/mo) is named Cut because it cuts the bill — cache, compression, prompt-cache injection. Route ($100) adds failover. Keys stay on the box. No model of any kind runs inside the process.
Free firewall, forever Hard-cap kill switch macOS · Linux · Windows 153 tests · 0 LLMs bundled
What one binary replaces
100%
Local-only free tier
2
Cache layers (exact + semantic)
5
Platforms (macOS/Linux/Win, arm64+x64)
$0
Cost of the free tier, ever
Install (pick one)
curl | sh
curl -fsSL \
https://halo-get.aperion.ai | sh
Docker
docker run --rm \
-v halo-data:/data -p 8787:8787 \
ghcr.io/aperionai/halo
Windows
Grab the .zip from
github.com/AperionAI/halo-dist
/releases
Source is closed, but the binaries and Docker image are fully public — no
GitHub auth needed for any install path. Full detail in docs/INSTALL.md.
60-second integration
01
Register an agent, point your runtime at Halo
OpenAI / Anthropic / OpenClaw
Halo mints a virtual key mapped to your real provider key (stored in your OS keychain — never on disk). Swap two env vars and every call now flows through the firewall. OpenClaw and Hermes get a one-command patch because env vars are not enough on those runtimes:
# 1. Register — the real key goes straight to your OS keychain.
halo agent add researcher --provider openai --key sk-...
# 2. Point your runtime at Halo instead of the provider.export OPENAI_API_KEY=sf_live_researcher_...# virtual key printed aboveexport OPENAI_BASE_URL=http://127.0.0.1:8787/v1# 3. Run it. OpenClaw: don't set env vars — they ignore them.
halo serve
halo openclaw apply --agent researcher
halo hermes apply --agent researcher
Anthropic works identically (--provider anthropic, ANTHROPIC_BASE_URL=http://127.0.0.1:8787). Hermes: halo hermes apply writes ~/.hermes/config.yaml and .env — env vars alone are not enough. Streaming passes through live. Buy Cut: deploy.langsmart.app/halo/buy/cut.
Global + per-agent soft/hard caps over a rolling window. The hard cap is enforced locally and always — a single request can't overshoot it, and it doesn't depend on any relay being reachable. halo kill <agent> revokes a key instantly; streaming gets a mid-stream stop-loss too.
03
Two-layer caching
cross-provider
Cut applies exact-match cache for byte-identical repeats, plus an optional semantic cache that catches reworded repeats — even across providers. Free still writes the exact-match cache so the dashboard can star what Cut would have saved. Cosine similarity is always re-checked at request time.
04
Compression & prompt-cache injection
Cut shrinks the wire body (phrase reduction + whitespace) and injects Anthropic cache_control on large/repeated system prompts, tool defs, and attachments. Free computes the same ratio and stars the dollars. That's the bill cut.
05
MCP cloak & taint
secret-safe
Halo fronts your MCP servers. Reference secrets in tool args as {{cloak:NAME}}; Halo resolves them only on the copy sent upstream and scrubs leaked values out of results. Reused directly from Aperion Shield's cloak/taint engine — not rebuilt.
06
Local dashboard
http://127.0.0.1:8788
A second, loopback-only web UI bundled into the same binary: live spend/savings, cache-hit rate, agent list with one-click revoke, and a settings editor for budgets/cache/relay — all reading the exact same free-tier local data as halo status/halo report. Reads need nothing beyond loopback access; writes require a local-only token from halo dashboard token that never leaves the machine.
CLI cheat-sheet
Command
What it does
halo agent add <name>
Register an agent, mint a virtual key, store the real key in your OS keychain.
halo serve
Run the proxy + the local dashboard (both on by default).
halo status
Live spend by agent and current caps.
halo report
Local COGS/savings view — works fully offline.
halo kill <agent>
Emergency stop: revoke a key, refused at once, zero network required.
halo dashboard token
Print (or --regenerate) the local token that gates dashboard writes.
halo embeddings set-key
Store the embedding API credential used by the semantic cache.
halo openclaw apply
Patch OpenClaw so traffic hits Halo. Env vars do not work on OpenClaw.
halo hermes apply
Patch Hermes config.yaml + .env. Env vars are not enough on Hermes either.
halo license apply
Paste the Cut/Route token from checkout. Restart halo serve.
Free / Cut / Route
Free (this binary)
Local budgets, hard-cap kill switch, halo kill — never paywalled
Starter denylist (cloud metadata + a few exfil sinks), true on install
MCP cloak/taint; uncloaked secrets in tool args are blocked
halo report + loopback dashboard, 7-day history
Stars what Cut would have saved on this install's traffic
Up to 3 registered agents
No account. Nothing leaves the machine if relay_url is unset
Cut $50 · Route $100
Cut applies cache, compression, prompt-cache injection — that's the bill cut
The honest comparison: LiteLLM is a stronger general routing layer. Hosted gateways add observability but put traffic through their cloud. Halo is narrower on purpose — one binary, keys on the box, Free is a real firewall, Cut is the bill cut.
Build from source · references
07
From a fresh checkout (licensees with repo access)
build
Rust 1.75+ stable. Own workspace, lean dependency tree, redb/SQLite single-file stores — no Redis, no Mongo, no Postgres.
cargo build --release
./target/release/halo --version
cargo test --release # 153 tests, all green
Public binaries:github.com/AperionAI/halo-dist/releases ·
Container:ghcr.io/aperionai/halo ·
Install guide:docs/INSTALL.md ·
Design notes:docs/DESIGN_REVIEW.md