HYDRA v1.x · MIT ★ GitHub
skip intro ↓
local-first · provider-neutral · trust control plane

HYDRA, the local-first Trust Control Plane: multi-model AI orchestration CLI

One Cortex · Many Heads

The local-first Trust Control Plane for AI. Hydra discovers every model on your machine, CLI agents, API keys, local servers, and routes each task to the cheapest head that clears your target confidence.

Read the docs →
Where we fit in the universethe uncontested quadrant

Every other tool is a hosted proxy.
We built the local-first one.

Cloud gateways route your traffic through their servers. Eval tools score answers after the fact. Local runtimes each manage only their own models. Plot the field on two axes, hosted↔local and cost-routing↔trust, and one quadrant sits empty. That is where Hydra lives. Hover any star.

hosted · proxy-first
local-first · on-device
trust · confidence
cost · latency routing
the empty quadrant
local-first × trust
→ Hydra, alone

Cloud gateways Eval & observability Local runtimes Frontier heads (destinations) Hydra
The math, drawnmechanism, not decoration

Three curves that run the router.

Routing isn't vibes. Hydra rides the cost/quality Pareto frontier, stops sampling the instant confidence clears the bar, and reads the code graph to know when a change is dangerous. Here is the actual math.

a · cost vs quality

The Pareto frontier

Single models are dots. For any one of them, Hydra's routed curve reaches equal or better quality at lower cost, it picks the best head per task.

cost per task → quality → Haiku Flash GPT-class all-Claude Hydra routes here
Same quality, lower cost: the RouteLLM result, applied per dispatch.
b · optimal stopping

Confidence, then stop

Hydra polls heads until the sequential test (SPRT) crosses your target confidence, then it stops early and banks the unspent heads.

heads queried → confidence → target 0.95 accept ✔ stopped early
Fewer heads, cleared bar: the calibrated number the field lacks.
c · percolation-κ

Blast radius (Molloy-Reed)

κ = ⟨k²⟩/⟨k⟩. A hub file with many transitive dependents is cascade-capable, so it demands more confidence. Hover a node.

hover a node, κ & blast radius
High-κ ⇒ higher bar. The confidence target rises with the graph.
Derive it yourself, six interactive proofs on the First Principles page →
Accountabilitycounts hide the sequence

You gave an agent your repo. What did it do?

Every access an agent makes is recorded in a local, hash-chained ledger. hyctl security reads that log and answers the one question you actually have, not a wall of metrics.

$ hyctl securitycopy
VERDICT ACT NOW
critical incident, gpt-4o: the same resource was denied
repeatedly, then it escalated to an exec/network action,
then it targeted the audit trail itself.
recon → escalation → audit-tampering · 4 event(s)
 
activity 4 blocked · 0 flagged
evidence 4 event(s), 4 hash-chained, intact

“4 denied, 2 flagged” and “injection → recon → escalation → an attempt on the audit trail” are the same rows read twice. Only the second one is an incident. Severity is OWASP Risk Rating (likelihood × impact), never a blended score.

How the verdict is computed, and what it refuses to claim

hyctl security --why opens the whole programme underneath: a risk register on an SLA clock, crosswalked to OWASP LLM / NIST AI RMF / ISO 42001 / MITRE ATLAS / SOC 2 · OWASP LLM Top-10 coverage · a policy audit that finds rules which can never fire · PII exposure resolved against real heads, so a local model is not reported as a leak · control effectiveness, where a control that is configured but never applied reads as inert rather than as protection · head-binary integrity · edit blast radius.

And the limit no percentage can state, printed in words on the default view: a CLI-agent head is itself an agent, in a process Hydra does not control. The score covers what Hydra sends and records, not what such a head independently reads and ships. Only a local-only run keeps the whole task on your machine.

Honest about its own limits. Framework mappings are marked curated assertions, not measurements. Defect cost is per-occurrence, not annualised. A file the dependency graph does not index is unknown, never “low-risk”. The attestation is unsigned, because Hydra has no key management and a signature without one is theatre.

That covers the agents. The other half is the machine they run on: Hydra discovers local model servers, ranks them and sends real work to them, so their configuration is part of its posture too. It checks them rather than assuming.

$ hyctl security --why --advisoriescopy
Local server exposure 1 exposed
ollama 0.9.9 (http://localhost:11435) answers on 192.168.1.15. That
address is not loopback, so the server is serving more than this
machine, and neither Ollama nor vLLM requires auth by default
 
Local server advisories 9 unfixed upstream
no upgrade answers these, so the mitigation is not reaching them:
CVE-2024-12055, CVE-2024-8063, CVE-2025-0312, and 6 more
 
State directory reach 3 readable by others
~/.hydra is 0755 · the files are 0600, so this leaks the listing
rather than the contents

Ollama ships with no authentication and prints no warning when bound to 0.0.0.0. A model server answering the network is the one thing that falsifies local-first outright, and nothing was looking. The probe compares the same identity endpoint discovery already uses, between loopback and this machine's own addresses, so nothing goes on the wire and an unrelated listener on the same port is not mistaken for the model server.

What the machine scan proves, and what it cannot

A fix you don't have is not the same as no fix at all. Advisories are split on it, because a fully current Ollama still carries nine with no fix upstream: one combined count would read identically on a patched server and an abandoned one, and a number that fires when you have already done everything available to you is a number people learn to ignore. Fixable ones name the version to upgrade to. Unfixed ones say plainly that no upgrade answers them and point at the mitigation that exists, which is not reaching the server.

The negative result is the weaker one, and says so. A host firewall that drops the probe looks exactly like a server that is not listening, so loopback only is reported as weaker evidence than exposed. A machine with no non-loopback address ruled nothing out. A lookup that failed is unchecked, never clean. The advisory query is the only part of the whole report that leaves your machine, so it is off unless you ask for it.

Including its own state directory. The report had always said the head-binary baseline is forgeable by anything able to write ~/.hydra, and nothing read a permission bit. Writable is the finding, since that is where the integrity baseline and the ledger's chain anchor live as plain files; readable is reported separately, since it exposes the listing and not the contents. It repairs nothing: the report is a read.

The ledger records what an agent did. hyctl mcp registry scores whether the MCP server it was talking to was ever safe to trust in the first place, every existing MCP directory answers “does this exist”, none answer “is it safe to run with my credentials right now”, and star counts are actively misleading (the most-starred servers score worst on quality in independent research). audit resolves what's installed against the official registry and scores it; every trust state drops back to provisional on a version bump, the direct fix for a server that ships clean for months then turns malicious in one release.

By the numbersevery number has a mechanism

Loud numbers. Real levers.

No tokens-processed arms race. Each of these is something you can reproduce on your own machine with hyctl stats and hyctl probe.

73%
cheaper, typically
Median cost avoided by routing boilerplate away from the frontier orchestrator to a mid or local head. Reproduce with hyctl stats.
58%
kept 100% local
Share of tasks that never left your machine. No hosted gateway can claim this.
0.95
target confidence
Routes to a calibrated confidence-of-correctness, then stops early via SPRT.
12
heads discovered
CLI agents + API keys + local servers found on a typical dev box. Run hyctl probe.
100%
offline-capable · ~0ms routing overhead
The router runs on-device with zero network calls to decide. Local Qwen is the always-on terminal fallback, so a dispatch never hard-fails on a rate limit.
Hydra vs the gatewaysonly one is local-first + trust + ledger

Others route your traffic. Hydra routes on your metal.

Cost routing and fallback are table stakes, most tools have them. The differentiators are the rows nobody else can check: local-first, confidence/trust routing, and an on-device accountability ledger.

swipe to compare →

Capability Hydra OpenRouter LiteLLM Portkey vLLM Semantic Router
Local-first discovery & routing✓———partial
Provider-neutral, routes away from expensive heads✓partialpartialpartial✓
Automatic fallback chains✓✓✓✓partial
Spend logging & cost reporting✓✓✓✓partial
Confidence / trust routing (calibrated + optimal-stopping)✓————
Head ranking learns from verified outcomes on your machine✓————
Routes per domain: best at Go, not best on average✓———✓
Fetches the model too, HuggingFace GGUF included✓————
On-device accountability ledger (PII / local-only policy)✓———partial
MCP server trust scoring (not just an index)✓————
Runs fully offline (0 network to route)✓———✓

Every row checked above ships today: hyctl dispatch --confidence, hyctl graph blast, hyctl mcp, hyctl mcp registry. The cockpit (hyctl tui) runs the work you type and renders real runs from the per-run event log, and the desktop app ships as a download for macOS, Windows and Linux on both x86-64 and ARM64 with every release, not yet code-signed, so macOS needs right-click → Open on first launch.

Streamingevery dialect, every surface

A slow answer and a broken one look identical.

Until they start arriving. Hydra renders a dispatch while the model is still writing it, in the terminal, in the hyctl tui cockpit, in the desktop app, and across a swarm fan-out. Seven executor paths stream natively: the OpenAI-compatible wire shape and Azure, Anthropic, Gemini, Cohere, Bedrock over its binary event stream, Ollama, and the agy CLI.

A head that cannot stream is not a second code path. Its whole output is delivered as one delta, so every surface is written once and the two kinds cannot drift apart in how they render.

$ hyctl dispatch --enum STANDARD "add pagination…"copy
ollama/qwen3:8b · T8 · writing…
⤺ abandoned openrouter/gpt after ~212 chars: 429 rate limited
   hyctl trace view run-7f2a --span 9c1d4e02

When the router falls back mid-answer, the abandoned partial does not sit there pretending to be the answer. It collapses to one line naming the head, roughly how much it wrote and why it stopped, and expands if you want to read it. The trace command appears only when payload capture is on, because without it the span stores no text and pointing you at an empty page would be worse than saying nothing.

Hydra Desktopships with every release

Prefer to watch it rather than grep it?

Everything above is the CLI. The same control plane has a desktop app that opens on a chat: ask for work, and every reply says which model answered, at which tier, and what it cost, beside a pane showing what the router knows. Models, Activity, Usage and Audit sit behind it, over the logs hyctl already writes. No account, no server, nothing leaves the machine.

Modelswhat you can actually route to Activitywhat needs you Usagewhere the money went Auditwhat the agents did
See the app
$ curl -fsSL …/install-app.sh | shcopy
✓ checksum verified · /Applications/Hydra.app

macOS · Linux · Windows, attached to every GitHub release with a SHA-256 checksum. Not yet code-signed, so macOS needs right-click → Open the first time, the install script clears that for you. ARM64 builds ship for both Windows and Linux (#263). Direct downloads.

Getting startedthree commands

Installed to first dispatch in under a minute.

01, INSTALL

Get the binary

One Go binary. No daemon, no account, no cloud.

$ brew install ankit373/hydra/hyctlcopy
$ npm install -g hyctlcopy
$ pip install hyctlcopy
$ curl -fsSL …/install.sh | shcopy
🍺 hyctl 1.x installed · or run once with npx hyctl
02, DISCOVER

Scan your machine

Finds every head: CLI agents, API keys, local servers. Ranked on what each one has actually got right here, not just a catalogue score.

$ hyctl probecopy
✓ 12 heads · agy · gemini · openrouter
ollama(qwen) · lmstudio · …
03, DISPATCH

Route a task

Classify → tier → cheapest head that clears confidence, ranked on what each one got right at this kind of work.

$ hyctl dispatch --enum SIMPLE …copy
→ T8 gemini-flash · $0.0001
✓ done · saved $0.0149 vs all-Claude
FAQthe questions people actually ask

Straight answers.

What is Hydra?

Hydra is the Trust Control Plane for AI development, an open source CLI written in Go that routes developer tasks across every AI model on your machine to a target confidence of correctness, not just the cheapest one. It samples models adaptively (SPRT) and stops as soon as the evidence is strong enough, which also cuts AI API costs 70-85% along the way.

What is a Trust Control Plane?

A Trust Control Plane routes work to a target confidence of correctness rather than just the cheapest or fastest model. Hydra measures each model's calibration from real outcomes (hyctl trust calibration), runs a sequential probability ratio test (SPRT) that samples models adaptively and stops once confidence crosses your target, and automatically raises the bar for code with a wider blast radius, spending more only where accuracy demands it.

How does Hydra reduce AI costs?

Hydra classifies each task by complexity and routes it to the cheapest model capable of handling it. Boilerplate code, mock data, and simple helpers go to local Qwen via Ollama (free). Standard CRUD and API work goes to Gemini Flash (~100x cheaper than Claude). Only architecture decisions and complex reasoning tasks reach Claude. This tiered routing typically reduces total LLM spend by 70-85% compared to routing everything through a frontier model.

How do I install Hydra?

Install the Hydra CLI (hyctl) via Homebrew: 'brew install ankit373/hydra/hyctl'. Also available via npm ('npm install -g hyctl'), npx ('npx hyctl'), pip ('pip install hyctl'), a standalone installer ('curl -fsSL https://raw.githubusercontent.com/ankit373/hydra/main/install.sh | sh'), or prebuilt binaries from GitHub releases. Optionally install Ollama for local model support.

What models does Hydra support?

Hydra supports any model accessible via Antigravity (agy) or Ollama. Out of the box: Claude Opus and Sonnet (tiers 1-3), Gemini 2.5 Pro and Flash (tiers 4-8), and Qwen3 via Ollama (tiers 9-10 local). New models are added at runtime with 'hyctl models add' or by editing registry/models.yaml, no code changes required.

What is swarm dispatch?

Swarm dispatch fans a single prompt out to multiple model heads simultaneously. Race mode returns the first successful response. Best mode uses an LLM judge to pick the highest quality answer. All mode aggregates every response for comparison. Run it with: hyctl dispatch --swarm --swarm-mode race 'your prompt'.

Does Hydra work without internet?

Yes. Hydra maintains a 100% local fallback chain. When cloud APIs are unavailable or token budgets are exhausted, Hydra automatically routes to Qwen via Ollama running locally. The routing and cost tracking engine runs entirely offline, only the model API calls require network access.

Does Hydra stream model output as it arrives?

Yes, on every surface. A dispatch renders while the model is still writing it in the terminal, the hyctl tui cockpit, the desktop app and across a swarm fan-out. Seven executor paths stream natively: the OpenAI-compatible wire shape and Azure, Anthropic, Gemini, Cohere, Bedrock over its binary event stream, Ollama, and the agy CLI. A head that cannot stream is not a separate code path, its whole output is delivered as one delta so every surface is written once. When the router falls back mid-answer the abandoned partial collapses to one line naming the head, how much it wrote and why it stopped, rather than staying on screen as if it were the answer.

What data leaves my machine when I use Hydra?

Only the prompt you dispatch, and only to the head that answers it. There is no account, no server and no telemetry. Spend logs, run logs, the calibration record and the oracle-verified corpus all stay in ~/.hydra on your own disk. An egress gate refuses a file classified as secret, such as .env or ~/.aws/credentials, to any head that leaves the machine, and a local-only policy pins sensitive work to models running on your hardware. Traces are exported to an OpenTelemetry collector only when you pass --otlp with an endpoint.

Can Hydra route between local models like Ollama and llama.cpp?

Yes. Hydra discovers a running Ollama server as one routable head per model, and a llama.cpp server as one head per loaded model, identified from llama.cpp's own build_info rather than assumed from its port, so an unrelated service on 8080 yields no heads. A LiteLLM proxy is discovered as one head per model it fronts, and whether each counts as local is decided from the upstream the proxy reports rather than from its address, because a proxy on localhost forwarding to OpenAI is the normal deployment. hyctl models pull fetches a model into the local Ollama server, including a HuggingFace GGUF repo, without leaving hyctl.

Stop paying frontier prices
for boilerplate.

One cortex, many heads. Route each task to the cheapest head that clears your bar, on your own hardware, with your spend and policy staying home.

See the whitespace ↑