GaugeMesh

GaugeMesh

One endpoint for MCP capabilities and model routes—without losing identity, authority, budgets, deadlines, side-effect semantics, or causal evidence between protocols.

GaugeMesh is a local-first Rust developer preview. It is deliberately narrower than a general AI gateway: every adapter must preserve declared invariants or reject the operation before a side effect. Route selection is fixed-point, deterministic, and explainable. The base deployment is one binary with memory or SQLite; it needs no hosted control plane, Redis, PostgreSQL, Docker, or Kubernetes.

Install without Rust from the checksummed, attested GitHub Release or run the multi-architecture GHCR image. Crates.io is not a GaugeMesh distribution channel. The real stdio MCP server is gaugemesh mcp-stdio; its Official MCP Registry metadata is checked in as server.json.

The source tree also provides opt-in bounded durable Runs: caller-authored plans over the existing Tasks, verified file outcomes, explicit resume/cancel, and offline evidence verification. See that contract for the local Unix boundary and the external installed-binary qualification commands.

Two explicit first-use paths are available from release source:

• A neutral recoverable Run, with observable worker effects, restart/refusal cases and offline verification.
• An optional educational section-mechanics review, using the same public interface. Its original formulas stay outside the binary; standards catalog metadata is not an authorized rule implementation or approval.

Run the local proof

From a release archive:

gaugemesh demo

From source with Rust 1.88 or newer:

cargo run --locked --release -- demo

No account, credential, provider, network target, database, container, or existing MCP server is used. The command writes no file to the caller directory.

Actual output from the 0.1.0 release binary:

GaugeMesh demo
[ok] 2 MCP sources connected[ok] 1 model route connected[ok] colliding tool names isolated by capability identity: true[ok] 2 capabilities leased[ok] route selected under cost, deadline, and policy bounds[ok] deterministic failure reproduced[ok] recovery bounded to one attempt[ok] duplicate effects: 0[ok] invariants preserved or strengthened: 23/23[ok] cleanup complete: no owned child or listener remains
Route: local-model -> docs-a__searchDecision: sha256:169a6315aa69eb7fa3e3b5aae70ede14d4c9ec71c0281d217fd84201414567f1Evidence: sha256:9a9cdc8b673bab79ae96cf5aba5b7895d6e6e5f425407d1bd64da8701a1314e6

What the demo proves

• Two upstreams can expose the same native search name without sharing an authorization identity.
• A lease binds an exact principal, tenant, task, schema, capability set, expiry, scope, budgets, side-effect permission, and manifest digest.
• Hard route constraints run before an integer action score and stable tie breaker.
• One injected failure consumes the single retry budget; it cannot amplify.
• The checked translation preserved or strengthened 23 invariants with zero semantic loss.
• The read-only case observed zero duplicate effects and completed with no owned child process or listener.

The demo is deterministic fixture evidence, not a production-duration soak or security certification.

Inspect the route planner and its versioned decision contract independently. The final command uses a built-in fixture in which every candidate violates a hard constraint, so the output is a digest-bound denied decision rather than an unsafe fallback:

gaugemesh route explaingaugemesh route explain --decision-contractgaugemesh route explain --deny-allgaugemesh route schemagaugemesh route validate decision.json

Architecture

MCP clients --------------------+  /mcp                                |OpenAI-compatible clients ------+--> GaugeMesh --> invariant + policy boundary                                |         |             before executionMCP servers needing models -----+  /v1/*  +--> MCP stdio / Streamable HTTP                                          +--> OpenAI-compatible providers                                          +--> official/private registries
ResiliReplay ---------------------- verification only; never a production hop

GaugeMesh is an MCP server northbound and an MCP client southbound. It is an OpenAI-compatible server northbound and a client of configured compatible model providers southbound. Registry records are discovery metadata, not execution authority.

Add one MCP server

Create a strict loopback configuration:

gaugemesh init

Review and add a local stdio server. --command must resolve to an absolute executable and is launched with an argument array, never through a shell:

gaugemesh add mcp docs \  --command "$(command -v gaugemesh)" \  --arg mcp-stdio \  --protocol-revision 2025-11-25

add performs live discovery and writes the source only after tools, resources, templates, prompts, server identity, and revision are readable. serve loads reviewed sources into a bounded runtime, pins the capability snapshot, and rejects schema drift. Tools, resources, and prompts keep source-bound opaque identities even when readable aliases collide. Streamable HTTP sources use the same command with a reviewed --url; Registry search/inspect/approve is a separate trust path and never installs or executes a discovered package.

Add one model

The provider must expose a compatible /v1/models endpoint. To exercise the complete no-key setup, keep gaugemesh serve running in one terminal and add its built-in local model route from another:

gaugemesh serve

gaugemesh add model local-provider \  --base-url http://127.0.0.1:8090/v1/ \  --provider-model-id local \  --context-limit 8192 \  --max-output-tokens 1024 \  --cost-table-version local-2026-08-30

For a credentialed provider, pass the environment-variable name, not its value:

gaugemesh add model hosted \  --base-url https://provider.example.test/v1/ \  --provider-model-id reviewed-model \  --credential-env PROVIDER_API_KEY \  --cost-table-version contract-2026-08

Configured routes are checked against capability, context, deadline, token, money, retry, data, and side-effect limits before selection. Cost tables are version-bound; estimates are not presented as provider billing facts.

Connect an MCP client

Start the data and separately bound health listeners:

gaugemesh doctorgaugemesh listgaugemesh servegaugemesh connect generic-mcp

Loopback defaults are http://127.0.0.1:8090/mcp for Streamable HTTP, http://127.0.0.1:8090/v1 for the model API, and http://127.0.0.1:8092/healthz for health. The official MCP conformance client connects to /mcp separately for both supported revisions. GaugeMesh also has real RMCP integration tests as an upstream client over stdio and Streamable HTTP. Product-specific client installers are not emitted without installation evidence.

Connect an OpenAI-compatible client

Point a client that supports a custom base URL at GaugeMesh:

gaugemesh connect openai-compatiblecurl http://127.0.0.1:8090/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"local","messages":[{"role":"user","content":"hello"}]}'

The release gate also executes openai-python==3.6.0 against that base URL for model listing, chat completions, and Responses. The implemented surface is GET /models, POST /chat/completions, and POST /responses, with bounded JSON and SSE behavior. Unknown request fields are rejected. This is a verified subset, not complete OpenAI API compatibility.

Tool execution is off unless a request explicitly selects a GaugeMesh mode and bound:

x-gaugemesh-tool-mode: leasex-gaugemesh-max-tool-rounds: 1x-gaugemesh-deadline-ms: 3000

These extension headers are not OpenAI fields. An MCP server can call /v1/* directly for model access; deprecated MCP sampling is not silently converted. Unsupported sampling and elicitation paths return stable errors or enter an explicit approval backend.

Five invariant rules

1. A route is a typed trust-graph path; a display alias never identifies a node.
2. Principal, tenant, capability, schema, causal root, and provenance are conserved unless a checked delegation explicitly permits the transition.
3. Scope, delegated authority, deadline, money, tokens, and retries only shrink; data protection never decreases.
4. Optional translation loss has a bounded integer score; required semantic loss rejects before target execution.
5. Queue pressure, retry dissipation, and breaker hysteresis use ordinary, falsifiable software definitions. No physics analogy overrides the code.

Run gaugemesh route explain for the original 0.1.0 bare plan containing accepted and rejected candidates, integer score terms, the stable tie breaker, and policy/metric snapshot digests. Existing machine consumers retain that shape. Opt into the versioned selected wrapper with --decision-contract. gaugemesh route explain --deny-all returns the new contract with status: "denied", stable GM_ROUTE_NO_ELIGIBLE_CANDIDATE, every constraint rejection, and the snapshot digests. Route IDs must be unique, denied candidates must carry nonblank reasons, and candidate/reason ordering is canonical. Both selected and denied contracts include decision_digest, a SHA-256 digest over the canonical unsigned decision fields other than the digest itself.

The checked-in route-decision JSON Schema documents the wire contract. Save a decision and run gaugemesh route validate <file> to check its schema, digest, and derivable selection/denial invariants entirely offline. The digest is unsigned and recomputable integrity, not authentication against a party able to rewrite the whole decision. Decisions contain route IDs and constraint reasons; validation does not upload them, and they should be sanitized before sharing. The analogy boundary is documented in the physics model.

Safety boundaries

• Unauthenticated mode is loopback-only. Remote mode requires TLS, an explicit HTTPS public origin, exact OIDC issuer/audience/resource validation, required scopes, bounded JWKS caching, a trusted-proxy allowlist, and default-deny policy.
• API-key primitives use random material shown once, Argon2id hashes, tenant/scope binding, and revocation; the 0.1.0 remote listener authenticates OIDC bearer tokens rather than exposing an API-key administration service.
• Downstream bearer tokens are never passed upstream by default. Provider credentials remain environment or restricted-file references and are not ordinary SQLite values.
• Remote URLs reject unsafe schemes/address classes, pin approved DNS answers, bind the exact host/port and peer IP, disable automatic redirects, and bound response bodies.
• Stdio uses exact argv, kill_on_drop, startup/framing limits, restart budgets, and a security-partitioned process key. Unknown servers are non-shareable.
• Admission queues, request bodies, process output, SSE output, tool rounds, and shutdown waits are bounded. Cancellation propagates through owned resources.

See SECURITY.md, THREAT_MODEL.md, and the adversarial evidence. The bounded durable MCP Tasks route documents its separate failure and trust boundaries. GaugeMesh does not claim exactly-once execution, production readiness, universal client/provider support, official MCP status, MCP certification, or security certification.

Verified compatibility

Conformance-only synthetic capabilities are absent in normal operation. Pending or unscored extension checks are not counted. The recorded 0.1.0 conformance run did not advertise Tasks; current source advertises io.modelcontextprotocol/tasks only for 2026-07-28 when SQLite durable storage and at least one task-capable reviewed upstream are available. The caller must also declare Tasks support. The task route is integration evidence outside the older conformance counts, and none of these results is official certification. See the MCP matrix, durable Tasks guide, client levels, and conformance inventory.

Exercise the durable route explicitly from a native binary—no Rust toolchain, account, or provider is required:

gaugemesh verify --durable-tasks

This embedded qualification self-spawns a synthetic JSON provider over MCP stdio; that provider starts the bounded JSON worker as a separate real child process. It reopens its temporary SQLite router state and separately reports execution and artifact-verification outcomes. It is not a shipped general executor. GaugeMesh has no background task scheduler: after an upstream acknowledgement, deadline cancellation begins only on a later caller poll; a cancel acknowledgement is not observed termination. A changed upstream session can leave a nonterminal route reconciliation-only, and tasks/update is explicitly unsupported for durable routes.

ResiliReplay verification

ResiliReplay is optional and external:

gaugemesh verify --resilireplay

GaugeMesh invokes the exact published [email protected] executable with an argument array from sanitized temporary state. One genuine clean control and twelve explicit fault rows produced three passes and ten explicit failures. The two passing recovery rows are ResiliReplay trace-level synthetic timeout and deterministic-error mutations followed by a real bounded retry; 0.7.0 does not inject those faults into the MCP wire or server. Cleanup completed and the fault runs reported zero duplicate effects. The honest aggregate is PARTIAL. ResiliReplay emitted no MCP-RES v0.2 profile/evidence class for this command, so GaugeMesh makes no MCP-RES claim. Details and the evidence digest are in the verification record.

Development

cargo fmt --all -- --checkcargo clippy --workspace --all-targets --all-features -- -D warningscargo test --workspace --all-featurescargo test --doc --workspacecargo deny check advisories bans licenses sourcescargo audit --deny warnings

Rust 1.88 is the MSRV. Hosted gates cover current stable and MSRV on Ubuntu and Windows, stable on macOS, native release archives for Linux x64/ARM64, Windows x64, and macOS ARM64/x64, plus fuzzing, mutation, Miri, AddressSanitizer, conformance, ResiliReplay, an SPDX SBOM, checksums, attestations, container smoke, and clean archive execution.

Contributions must preserve typed invariants and include a test able to falsify the change. See CONTRIBUTING.md. Found a problem? Submit a sanitized reproducible bug, or share an integration and use case through the issue chooser. Report vulnerabilities through GitHub private vulnerability reporting, not a public issue.

License

Apache-2.0. Dependency and source-origin notes are in docs/research/DEPENDENCIES.md.