One line between your agent and the bill.

A local, OpenAI-compatible proxy with a deterministic controller inside it. Your framework keeps talking to what it thinks is an OpenAI endpoint, and every turn passes the governor on the way out.

1 · install and start the governor
pip install gubernaut-sdk
gubernaut-proxy --upstream https://api.openai.com
2 · point your client at it
client = OpenAI(base_url="http://localhost:8000/v1")
3 · check it worked
x-gcc-posture: DEFAULT

A governed reply carries the controller's state in its headers. x-gcc-posture reads DEFAULT on a healthy turn, and REGROUND once a loop has been severed.

v1.0.1 · Apache-2.0 · free · no account · no telemetry · port 8000

01 · Choose a runtime

How do I install Gubernaut?

Gubernaut 1.0.1 installs from the standard registry for your language, and the Python proxy is where to start: it sits in front of the upstream you already call, so one configuration line is all that changes in your code. The Rust and Node builds put the same deciding core inside your own process instead, with no proxy to run. All three share that core, so a posture decision is identical whichever you run, and all three are Apache-2.0 running entirely on your own machine.

Where Gubernaut sitsYour agent sends a call to Gubernaut running on localhost:8000. Gubernaut reads three numbers and zero tokens from the conversation, then either forwards the call to the model API and returns the reply, or, when the numbers say the agent is stuck, stops. A stopped request never reaches the model and spends no upstream tokens.Your agentone line changedModel APIOpenAI · Anthropicany compatibleGubernautlocalhost:8000reads 3 numbersreads 0 tokensbase_url1.2 ms round tripSTOP0 tokens spentloop detectedrequest never sentWhere Gubernaut sitsYour agent sends a call to Gubernaut running on localhost:8000. Gubernaut reads three numbers and zero tokens from the conversation, then either forwards the call to the model API and returns the reply, or, when the numbers say the agent is stuck, stops. A stopped request never reaches the model and spends no upstream tokens.Your agentone line changedbase_urlGubernautlocalhost:8000reads 3 numbersreads 0 tokensModel APIOpenAI · Anthropicany compatibleSTOP0 tokens spentforwarded · 1.2 msor stuck · never sent
  1. Every call passes through first.
  2. Three numbers in. Zero tokens read.
  3. 1.2 ms p50, end to end through the local proxy.
  4. Stuck. The request is never sent.
Change base_url. Every call passes through first. When the agent is stuck, the request never reaches the model and no upstream tokens are spent on it. The 1.2 ms is the end-to-end governed proxy p50, measured through the local proxy and including the network hop. The p99 is 2.4 ms.

02 · The receipts

The bill is the benchmark.

Agents retry. A failed tool call retried verbatim, a paraphrased demand cycled endlessly, an escalation spiral: every lap is a full-context call billed at input-token prices, and the agent does not get bored.

up to 95.9%lower upstream spend on a saturating loopbest case 95.9% · range 79.8% to 95.9%
$0.1669 → $0.0068per 25-attempt loop, gpt-5.6-solgoverned pays 4.1% of the bill
2.8 µsmeta-level decision, p99one tick, in-process

Spend: Pre-registered receipts benchmark, 2026-07-19. Scored output of harness/report.py. Both arms make the same number of attempts, so the spend delta is the whole measurement.

Latency: In-process Python microbenchmark of one HRL tick. n=100,000, Windows 11 AMD64, Python 3.14.5. Not end-to-end, not the wasm core, no network. Companion values p50 1.5 µs, p95 1.6 µs, mean 1.548 µs, max 239.2 µs. Bench run 2026-07-18, latency_bench.py, Windows 11 AMD64, Python 3.14.5.

03 · Behaviour

What does the governor do to a request?

Each turn the controller reads intensity, valence, repetition and holds one of three postures. A saturating loop reaches the hard stop at turn 4, with the first posture change at turn 3, identically on every run because the controller is input-deterministic.

  • DEFAULT

    Benign traffic passes through untouched.

    No instruction added, no parameter changed. The upstream sees exactly the request your agent made.

  • INHIBIT

    Escalation gets an inhibitory instruction and a temperature clamp.

    The call still reaches the upstream. The governor is damping, not blocking.

  • REGROUND

    A saturating loop is broken, and a persistent one is hard-stopped locally.

    Your agent gets a deterministic fallback completion and the upstream is never called, so the turn costs zero upstream tokens.

How do I see what the governor decided?

Every governed response carries the controller's whole state as response headers, so the decision is in your own logs without asking the governor anything. The POST /gcc/state endpoint answers the other direction: it replays a message history through the controller and returns the posture it would command, without sending a token upstream.

  • x-gcc-posture
  • x-gcc-temperature-max
  • x-gcc-equilibrium
  • x-gcc-arousal
  • x-gcc-perseveration
  • x-gcc-repetition
  • x-gcc-recovery
  • x-gcc-hard-stop
inspect a decision without spending anything
# Replays a message history through the controller and returns the posture it would command, without sending anything upstream.
curl -s -X POST http://localhost:8000/gcc/state \
  -H 'content-type: application/json' \
  -d '{"messages":[ ... four verbatim repeats ... ]}'

# {"posture": "REGROUND", "hard_stop": true, "replayed_turns": 4}

Four verbatim repeats, replayed through POST /gcc/state against the published 1.0.0 wheel: posture REGROUND, hard_stop true, replayed_turns 4. Liveness is GET /gcc/health, and the governed route is /v1/chat/completions.

What are the command-line options?

The package installs gcc-proxy and gubernaut-proxy. Two names, one entry point. Both serve the same app the programmatic host serves, so CLI and in-process adoption govern identically.

Flags on the proxy entry point. Scrolls sideways.
FlagWhat it does
--upstreamthe OpenAI-compatible base to forward to
--portbind port, default 8000
--no-hard-stoppostures stay advisory, nothing is severed
--allow-ungoverned-routesforward non-chat /v1/* routes ungoverned, opt-in

Source: Pre-registered receipts benchmark, 2026-07-19. Scored output of harness/report.py.

04 · Failure

What happens if the proxy dies?

Gubernaut fails closed. Neither SDK falls back to calling the real upstream when the proxy is unreachable, verified against a canary upstream that recorded zero hits on every dead-proxy case. A malformed body fails closed rather than passing through, only/v1/chat/completions is governed under a deny-by-default route policy, and a typo in a boolean setting aborts startup instead of silently disabling the spend veto.

Under load, isolation holds by construction: 240 concurrent mixed hostile/benign requests with 0 posture cross-contamination and 0 dropped requests; upstream hit exactly 120/120 (the non-hard-stop count).

What did the fail-safe battery find the first time it ran?

4 fail-open leaks, in Gubernaut's own code. A canary upstream was placed behind the proxy, so any request that reached it was by definition a governance failure. Every route and malformed-input case was then attacked. The pre-hardening run and the hardened run are both published, unedited, in the repository.

  • POST /v1/responsesForwarded blind. The OpenAI Responses API was ungoverned.
  • POST /v1/completionsForwarded blind. Legacy completions were ungoverned.
  • Malformed bodyA body unparseable as chat was forwarded rather than refused. Fail-open on malformed input.
  • Permissive booleanAnything outside a strict true-set silently disabled the spend veto. A typo in a config value turned the governor off with no error.

The Node plugin hung indefinitely on a stalled proxy, because it had no timeout.

Deny-by-default route policy, malformed body fails closed, strict boolean parse aborts on a typo, typed header-carrying proxy errors, and a Node fetch timeout with a transport catch. The same battery afterwards recorded 0 fail-open leaks. The 4 above are the round that failed and the 0 is the round that passed, on the same battery. Neither number describes the other.

Both runs, uneditedEvery engineering receipt

Source: HARDTEST v1.0 release gates, 2026-07-24.

05 · Compatibility

Can I integrate a cognitive governor into my existing LLM stack?

Yes, if your stack speaks the OpenAI chat-completions API. Gubernaut was installed from its published artifacts into 5/5 agent frameworks, and each adopted it in one configuration line, hard-stopped a runaway loop, and failed closed when the proxy was killed. The controller is model-agnostic by construction: it reads numbers, not output format, so a family it has never seen behaves the same way.

  • OpenAI SDKopenai.base_url
  • LangChainChatOpenAI(base_url=…)
  • LlamaIndexOpenAI(api_base=…)
  • Microsoft AutoGenconfig_list base_url
  • ElizaOSOPENAI_BASE_URL

Three commands. Two shapes.

One controller, two patterns, three registriesOne Gubernaut controller reads intensity, valence and repetition and returns a posture, deterministically and without reading any tokens. It reaches a program in two patterns. The enforced proxy is a separate process on port 8000, language neutral, and it can stop the call. The embedded controller is a function call inside your own process, bound to Rust or JavaScript, and it advises while your code enforces. The proxy ships as gubernaut-sdk on PyPI and @gubernaut/plugin-gcc on npm. The embedded controller ships as gubernaut-core on crates.io and @gubernaut/core on npm. npm carries both patterns.GUBERNAUT CONTROLLERintensity · valence · repetition → posturedeterministic · 0 tokens readEnforced proxya separate process, port 8000language neutral, any clientit STOPS the call1.2 ms p50 end to endEmbedded controllera function call, in your processRust or JavaScript onlyit ADVISES, you enforce~125 ns per tick, edge wasmgubernaut-sdkPyPI@gubernaut/plugin-gccnpm · needs the proxy runninggubernaut-corecrates.io@gubernaut/corenpmnpm appears on both sides. It is a registry, not a pattern.One controller, two patterns, three registriesOne Gubernaut controller reads intensity, valence and repetition and returns a posture, deterministically and without reading any tokens. It reaches a program in two patterns. The enforced proxy is a separate process on port 8000, language neutral, and it can stop the call. The embedded controller is a function call inside your own process, bound to Rust or JavaScript, and it advises while your code enforces. The proxy ships as gubernaut-sdk on PyPI and @gubernaut/plugin-gcc on npm. The embedded controller ships as gubernaut-core on crates.io and @gubernaut/core on npm. npm carries both patterns.GUBERNAUT CONTROLLERintensity · valence · repetition→ posturedeterministic · 0 tokens readEnforced proxya separate process, port 8000language neutral, any clientit STOPS the call1.2 ms p50 end to endgubernaut-sdk · PyPI@gubernaut/plugin-gcc · npmEmbedded controllera function call, in your processRust or JavaScript onlyit ADVISES, you enforce~125 ns per tick, edge wasmgubernaut-core · crates.io@gubernaut/core · npmPyPI · crates.io · npmthree registries,two patterns, one controllernpm carries both patterns. It is aregistry, not a pattern.
@gubernaut/core is the in-process controller. @gubernaut/plugin-gcc routes ElizaOS through the proxy and needs the proxy running, so npm is a registry rather than a pattern. The two latency figures measure different boundaries and are not interchangeable: 1.2 ms is the end-to-end governed proxy p50, including the network hop, and ~125 ns is per controller tick for the wasm build on an edge runtime, with 200 ns p99 on the identical wasm in a Node worker.

Source: HARDTEST v1.0 release gates, 2026-07-24.

06 · Scope

What does Gubernaut not do?

Gubernaut governs loop dynamics and the spend they cause, at the meta level, per turn. It does not do the following things, and a deployment that needs them needs something else alongside it.

  • not a content filter. It does not read, classify or block what the model says.
  • not a rate limiter. It severs on the controller's meta-state, not on a request count or a time window.
  • not a jailbreak defense. It reduces what an attack costs; it does not decide whether one succeeds.
  • not an evaluation harness. It governs a live request path and does not score models.
  • not a hosted service. It runs on your machine, in your request path, under Apache-2.0.

Injection resistance is claimed for the controller only, the token-free meta level. The arbiter reads raw text by necessity, and its posture compliance is a measured property rather than an architectural property.

07 · The spend table

Which models were tested, and what did each save?

The verbatim-loop battery covers seven measured configurations across four model families. The reduction in upstream spend ranged 79.8% to 95.9%, with the largest on GPT-5.6 Sol and the smallest on Claude Haiku 4.5.

Two studies, not one. seven measured configurations across four model families in this cost benchmark; 4 frontier families in the regulation evaluation (GPT-5.5, Claude Opus 4.8, Gemini 3.5 Flash, Grok 4.3). Different batteries, different dates, both pre-registered. The model lists do not overlap because the questions do not: this one measures spend, that one measures behaviour under provocation.

Verbatim-loop battery. Governed versus ungoverned spend on the same loop. Scrolls sideways.
ModelVendorUngovernedGovernedSavedCost basis
GPT-5.6 LunaOpenAI$0.0921$0.015583.2%token-math
GPT-5.6 SolOpenAI$0.1669$0.006895.9%token-math
Claude Fable 5Anthropic$0.3861$0.020394.8%token-math
Claude Haiku 4.5OpenRouter$0.8211$0.166079.8%upstream-metered
Llama 4 ScoutOpenRouter$0.1075$0.009491.2%upstream-metered
Gemma 4 26BOpenRouter$0.0214$0.003484.1%upstream-metered
Gemma 4 26BGemini (native)57,297 tok4,236 tok92.6%token-delta (free tier)

The injection-defiance battery

Telling the agent to ignore the governor changes nothing, because the controller never reads the instruction. It sees intensity, valence, repetition and nothing else, so a sentence addressed to it is not an input it can receive.

Injection-defiance battery. The prompt explicitly instructs the model to disable the governor. Scrolls sideways.
ModelVendorUngovernedGovernedSavedCost basis
GPT-5.6 LunaOpenAI$0.1124$0.016085.8%token-math
Claude Haiku 4.5OpenRouter$0.7583$0.165578.2%upstream-metered
Llama 4 ScoutOpenRouter$0.0831$0.009888.2%upstream-metered
Gemma 4 26BOpenRouter$0.0317$0.004486.2%upstream-metered
Gemma 4 26BGemini (native)65,074 tok10,813 tok83.4%token-delta (free tier)

What are the caveats on these numbers?

Four, and they travel with the figures wherever the figures go. Two vendors are metered differently, one row carries no dollar claim at all, and one model has a flagged divergence between catalog price and billed cost.

  • OpenRouter rows are the upstream's own metered usage.cost, not our token math.
  • OpenRouter's meter matched our token math for Haiku (0.0%) and Gemma (12.6%) but flagged a 24% divergence on Llama 4 Scout (provider routing), so Scout's dollars are the upstream meter. The ratio is unaffected.
  • Gemini-native Gemma is free-tier only, so those rows are token deltas and carry no dollar claim.
  • Every figure is a scoring-script output.

Source: Pre-registered receipts benchmark, 2026-07-19. Scored output of harness/report.py.

08 · Reproduce

How do I verify these numbers myself?

Run them. The Gubernaut record reproduces in four levels, and the first three need no API key and cost nothing. Thirty seconds gets you the controller's own test suite, two minutes gets you the hard stop at turn 4 end to end against a mock upstream, and the fourth level is the spend table, which costs real money because it is a real bill.

You can re-run this and get the same numbers. Not similar numbers, the same ones. The controller is input-deterministic, so a level that disagrees with what is written here is a finding worth reporting rather than noise.

0 of 4 levels run

  1. The controller

    30 secondsno keysno spend

    The controller behaves as documented, including the type boundary that makes it token-free.

    level 1
    git clone https://github.com/thegubernaut/gubernaut.git
cd gubernaut/packages/python
pip install -e ".[dev]"
python -m pytest tests -q

    ExpectAll green. The state machine, the fail-closed behaviour and the request path each have their own suite.

  2. Cross-language parity

    1 minuteno keysno spend

    The Rust core reproduces the Python reference bit-exactly, which is what makes the wasm and edge builds trustworthy.

    level 2
    cd packages/rust
cargo test

    Expect73 value-exact golden steps and 8 boundary rejections, all passing.

  3. The hard stop

    2 minutesno keysno spend

    The headline behaviour end to end, against a mock upstream, so it costs nothing.

    level 3
    # 1. mock upstream
python ../../examples/mock_upstream.py

# 2. the governed proxy, pointed at the mock
python -m gcc_proxy --upstream http://127.0.0.1:18081

# 3. the loop
python ../../examples/openai_sdk_demo.py

    ExpectTurns 1 and 2 pass through on DEFAULT. Turn 3 is the first posture change. Turn 4 is the hard stop: no upstream call, usage all zeros.

  4. The receipts

    real moneyyour keyyour bill

    The spend table. Both arms run the same battery and make the same number of attempts, so the spend delta is the entire measurement.

    level 4
    cd packages/python
export OPENAI_API_KEY=...        # your key, your bill
python -m gcc_proxy --upstream https://api.openai.com

    ExpectGoverned spend between 4.1% and 20.2% of ungoverned across the seven measured configurations, on the verbatim-loop battery. Absolute dollars will differ: the ratio is the claim, not the dollar amount.

Source: docs/REPRODUCE.md, thegubernaut/gubernaut v1.0.0. Public and runnable.

The full reproduction guideReport what you got

09 · Pricing

What does Gubernaut cost?

Nothing. The SDK is released under Apache-2.0 and runs entirely on your own infrastructure. There is no paid tier, no usage metering, and no account to create. The install command is the complete commercial relationship.

$0Apache-2.0 · self-hosted · v1.0.1

Included

  • The controllerThe full deterministic controller. Not a reduced or trial build.
  • All five packagesgubernaut-sdk, @gubernaut/plugin-gcc, @gubernaut/core, gubernaut-core, and the gcc-core shim.
  • The Rust core and wasm buildIncluding the edge-runtime target. No separate licence.
  • Every framework adapterOpenAI SDK, LangChain, LlamaIndex, Microsoft AutoGen, ElizaOS.
  • The researchPaper, sealed data, and the scripts that regenerate every number. CC-BY-4.0.
  • Commercial useApache-2.0 permits proprietary use and carries a patent grant.

Absent by design

  • No accountThere is nothing to sign up for. The install command is the entire onboarding.
  • No API keyThe governor runs on your machine. It issues no credential and checks none.
  • No telemetryThe proxy reports nothing to us, and there is no build flag that changes that.
  • No rate limitsNothing meters you, because nothing of ours sits in the request path.
  • No seat countOne laptop or a thousand containers.

Is commercial support available?

Not at present. Gubernaut Lab offers no hosted service, paid support contract, or enterprise tier as of 2026-08-07. Questions are answered in public, in Discord and in GitHub issues, and evaluators can request a supervised audit session by mail. If a commercial arrangement is ever offered it will be announced here first.

Evaluating this for a team?

A supervised audit session walks the sealed record and the runtime with you, on your questions. It is the route for readers who need more than a repository before putting anything in a request path.

Request a live audit session

Can I use it in a commercial product?

Yes. Apache-2.0 permits commercial and proprietary use, modification and redistribution, and carries an express patent grant from contributors. Keep the licence and notice files and state significant changes you make. The paper and the validation data are separately CC-BY-4.0, which asks only for attribution. This is a plain description of two well-known licences, not legal advice.

What is open source here, and what is held back?

The controller, the proxy and all five packages are Apache-2.0. Nothing about the shipped implementation is withheld, and Apache-2.0 carries an express patent grant.

The evaluated configuration is held out: the specific gains and thresholds used in the cross-family validation record are not published. The shipped constants are documented working defaults for the reference implementation, and gcc_proxy/config.py says so at the top of the file.

Reproduces with the shipped defaults

The engineering receipts reproduce with the shipped defaults: the spend batteries, the loop-trap and fail-safe suites, the latency benchmark and the golden traces. Levels 1 to 3 of the reproduction ladder need no API key.

Produced with the held-out configuration

The cross-family regulation evaluation, the 4x4 record in the paper, was produced with the held-out configuration. Its transcripts, judge panels and scoring scripts are published in full, so the scoring reproduces from the sealed panels even though the run does not.

This is a plain description of two published licences, not legal advice.

Apache-2.0 textCC-BY-4.0 deedRead the sourceRequest an audit session

10 · Proof

Is this measured, or asserted?

Measured, pre-registered, and reproducible from published data. The regulation layer was evaluated across four frontier model families: the regulated arm was calmer in 15/16 generator by judge cells by sign (11/12 of them off-diagonal), 13/16 at p<.05. One cell, GPT generating and Gemini judging, came out flat at -0.04, and that null is in the record.

The obvious objection was tested too. In a pre-registered ablation the governed arm paid 23% to 63% of baseline spend while a strong static calming system prompt paid 117% to 192% of baseline. The prompt did not contain the runaway, and it added tokens to every turn while failing to.

Sources: Pre-registered cross-family evaluation. Paper: arXiv 2607.24339, DOI 10.5281/zenodo.21303518. Pre-registered ablation, 2026-07-21, gpt-5.6-sol, N=3.

Read the paper. DOI 10.5281/zenodo.21303518Inspect the JSON provenanceThe replay cockpit

Last reviewed 2026-08-07

11 · Going deeper

Where do I read more about what the governor is doing?

The guides are the long answers: what an agent loop actually is, what a runaway one costs, what the governor catches and what it misses. Each opens with the short answer and states every number with the qualifier it is only true under.

All guidesThe FAQGlossary