{
  "markdown": "# GaugeMesh\n\nOne endpoint for MCP capabilities and model routes—without losing identity,\nauthority, budgets, deadlines, side-effect semantics, or causal evidence between\nprotocols.\n\nGaugeMesh is a local-first Rust developer preview. It is deliberately narrower\nthan a general AI gateway: every adapter must preserve declared invariants or\nreject the operation before a side effect. Route selection is fixed-point,\ndeterministic, and explainable. The base deployment is one binary with memory or\nSQLite; it needs no hosted control plane, Redis, PostgreSQL, Docker, or\nKubernetes.\n\nInstall without Rust from the checksummed, attested\n[GitHub Release](https://github.com/aliengineering-byte/gaugemesh/releases) or\nrun the multi-architecture GHCR image. Crates.io is not a GaugeMesh distribution\nchannel. The real stdio MCP server is `gaugemesh mcp-stdio`; its Official MCP\nRegistry metadata is checked in as [`server.json`](server.json).\n\n## Run the local proof\n\nFrom a release archive:\n\n```sh\ngaugemesh demo\n```\n\nFrom source with Rust 1.88 or newer:\n\n```sh\ncargo run --locked --release -- demo\n```\n\nNo account, credential, provider, network target, database, container, or\nexisting MCP server is used. The command writes no file to the caller directory.\n\nActual output from the `0.1.0` release binary:\n\n```text\nGaugeMesh demo\n\n[ok] 2 MCP sources connected\n[ok] 1 model route connected\n[ok] colliding tool names isolated by capability identity: true\n[ok] 2 capabilities leased\n[ok] route selected under cost, deadline, and policy bounds\n[ok] deterministic failure reproduced\n[ok] recovery bounded to one attempt\n[ok] duplicate effects: 0\n[ok] invariants preserved or strengthened: 23/23\n[ok] cleanup complete: no owned child or listener remains\n\nRoute: local-model -> docs-a__search\nDecision: sha256:169a6315aa69eb7fa3e3b5aae70ede14d4c9ec71c0281d217fd84201414567f1\nEvidence: sha256:9a9cdc8b673bab79ae96cf5aba5b7895d6e6e5f425407d1bd64da8701a1314e6\n```\n\n## What the demo proves\n\n- Two upstreams can expose the same native `search` name without sharing an\n  authorization identity.\n- A lease binds an exact principal, tenant, task, schema, capability set,\n  expiry, scope, budgets, side-effect permission, and manifest digest.\n- Hard route constraints run before an integer action score and stable tie\n  breaker.\n- One injected failure consumes the single retry budget; it cannot amplify.\n- The checked translation preserved or strengthened 23 invariants with zero\n  semantic loss.\n- The read-only case observed zero duplicate effects and completed with no\n  owned child process or listener.\n\nThe demo is deterministic fixture evidence, not a production-duration soak or\nsecurity certification.\n\nInspect the route planner and its versioned decision contract independently.\nThe final command uses a built-in fixture in which every candidate violates a\nhard constraint, so the output is a digest-bound `denied` decision rather than\nan unsafe fallback:\n\n```sh\ngaugemesh route explain\ngaugemesh route explain --decision-contract\ngaugemesh route explain --deny-all\ngaugemesh route schema\ngaugemesh route validate decision.json\n```\n\n## Architecture\n\n```text\nMCP clients --------------------+  /mcp\n                                |\nOpenAI-compatible clients ------+--> GaugeMesh --> invariant + policy boundary\n                                |         |             before execution\nMCP servers needing models -----+  /v1/*  +--> MCP stdio / Streamable HTTP\n                                          +--> OpenAI-compatible providers\n                                          +--> official/private registries\n\nResiliReplay ---------------------- verification only; never a production hop\n```\n\nGaugeMesh is an MCP server northbound and an MCP client southbound. It is an\nOpenAI-compatible server northbound and a client of configured compatible model\nproviders southbound. Registry records are discovery metadata, not execution\nauthority.\n\n## Add one MCP server\n\nCreate a strict loopback configuration:\n\n```sh\ngaugemesh init\n```\n\nReview and add a local stdio server. `--command` must resolve to an absolute\nexecutable and is launched with an argument array, never through a shell:\n\n```sh\ngaugemesh add mcp docs \\\n  --command \"$(command -v gaugemesh)\" \\\n  --arg mcp-stdio \\\n  --protocol-revision 2025-11-25\n```\n\n`add` performs live discovery and writes the source only after tools, resources,\ntemplates, prompts, server identity, and revision are readable. `serve` loads\nreviewed sources into a bounded runtime, pins the capability snapshot, and\nrejects schema drift. Tools, resources, and prompts keep source-bound opaque\nidentities even when readable aliases collide. Streamable HTTP sources use the\nsame command with a reviewed `--url`; Registry search/inspect/approve is a\nseparate trust path and never installs or executes a discovered package.\n\n## Add one model\n\nThe provider must expose a compatible `/v1/models` endpoint. To exercise the\ncomplete no-key setup, keep `gaugemesh serve` running in one terminal and add its\nbuilt-in local model route from another:\n\n```sh\ngaugemesh serve\n```\n\n```sh\ngaugemesh add model local-provider \\\n  --base-url http://127.0.0.1:8090/v1/ \\\n  --provider-model-id local \\\n  --context-limit 8192 \\\n  --max-output-tokens 1024 \\\n  --cost-table-version local-2026-08-30\n```\n\nFor a credentialed provider, pass the environment-variable name, not its value:\n\n```sh\ngaugemesh add model hosted \\\n  --base-url https://provider.example.test/v1/ \\\n  --provider-model-id reviewed-model \\\n  --credential-env PROVIDER_API_KEY \\\n  --cost-table-version contract-2026-08\n```\n\nConfigured routes are checked against capability, context, deadline, token,\nmoney, retry, data, and side-effect limits before selection. Cost tables are\nversion-bound; estimates are not presented as provider billing facts.\n\n## Connect an MCP client\n\nStart the data and separately bound health listeners:\n\n```sh\ngaugemesh doctor\ngaugemesh list\ngaugemesh serve\ngaugemesh connect generic-mcp\n```\n\nLoopback defaults are `http://127.0.0.1:8090/mcp` for Streamable HTTP,\n`http://127.0.0.1:8090/v1` for the model API, and\n`http://127.0.0.1:8092/healthz` for health. The official MCP conformance client\nconnects to `/mcp` separately for both supported revisions. GaugeMesh also has\nreal RMCP integration tests as an upstream client over stdio and Streamable\nHTTP. Product-specific client installers are not emitted without installation\nevidence.\n\n## Connect an OpenAI-compatible client\n\nPoint a client that supports a custom base URL at GaugeMesh:\n\n```sh\ngaugemesh connect openai-compatible\ncurl http://127.0.0.1:8090/v1/chat/completions \\\n  -H 'content-type: application/json' \\\n  -d '{\"model\":\"local\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}'\n```\n\nThe release gate also executes `openai-python==3.6.0` against that base URL for\nmodel listing, chat completions, and Responses. The implemented surface is\n`GET /models`, `POST /chat/completions`, and `POST /responses`, with bounded JSON\nand SSE behavior. Unknown request fields are rejected. This is a verified subset,\nnot complete OpenAI API compatibility.\n\nTool execution is off unless a request explicitly selects a GaugeMesh mode and\nbound:\n\n```text\nx-gaugemesh-tool-mode: lease\nx-gaugemesh-max-tool-rounds: 1\nx-gaugemesh-deadline-ms: 3000\n```\n\nThese extension headers are not OpenAI fields. An MCP server can call `/v1/*`\ndirectly for model access; deprecated MCP sampling is not silently converted.\nUnsupported sampling and elicitation paths return stable errors or enter an\nexplicit approval backend.\n\n## Five invariant rules\n\n1. A route is a typed trust-graph path; a display alias never identifies a node.\n2. Principal, tenant, capability, schema, causal root, and provenance are\n   conserved unless a checked delegation explicitly permits the transition.\n3. Scope, delegated authority, deadline, money, tokens, and retries only shrink;\n   data protection never decreases.\n4. Optional translation loss has a bounded integer score; required semantic loss\n   rejects before target execution.\n5. Queue pressure, retry dissipation, and breaker hysteresis use ordinary,\n   falsifiable software definitions. No physics analogy overrides the code.\n\nRun `gaugemesh route explain` for the original `0.1.0` bare plan containing\naccepted and rejected candidates, integer score terms, the stable tie breaker,\nand policy/metric snapshot digests. Existing machine consumers retain that\nshape. Opt into the versioned `selected` wrapper with `--decision-contract`.\n`gaugemesh route explain --deny-all` returns the new contract with\n`status: \"denied\"`, stable\n`GM_ROUTE_NO_ELIGIBLE_CANDIDATE`, every constraint rejection, and the snapshot\ndigests. Route IDs must be unique, denied candidates must carry nonblank reasons,\nand candidate/reason ordering is canonical. Both selected and denied contracts\ninclude `decision_digest`, a SHA-256 digest over the canonical unsigned decision\nfields other than the digest itself.\n\nThe checked-in [route-decision JSON Schema](schemas/gaugemesh-route-decision-v1.schema.json)\ndocuments the wire contract. Save a decision and run\n`gaugemesh route validate <file>` to check its schema, digest, and derivable\nselection/denial invariants entirely offline. The digest is unsigned and\nrecomputable integrity, not authentication against a party able to rewrite the\nwhole decision. Decisions contain route IDs and constraint reasons; validation\ndoes not upload them, and they should be sanitized before sharing. The analogy\nboundary is documented in\n[the physics model](docs/architecture/PHYSICS_MODEL.md).\n\n## Safety boundaries\n\n- Unauthenticated mode is loopback-only. Remote mode requires TLS, an explicit\n  HTTPS public origin, exact OIDC issuer/audience/resource validation, required\n  scopes, bounded JWKS caching, a trusted-proxy allowlist, and default-deny\n  policy.\n- API-key primitives use random material shown once, Argon2id hashes,\n  tenant/scope binding, and revocation; the `0.1.0` remote listener authenticates\n  OIDC bearer tokens rather than exposing an API-key administration service.\n- Downstream bearer tokens are never passed upstream by default. Provider\n  credentials remain environment or restricted-file references and are not\n  ordinary SQLite values.\n- Remote URLs reject unsafe schemes/address classes, pin approved DNS answers,\n  bind the exact host/port and peer IP, disable automatic redirects, and bound\n  response bodies.\n- Stdio uses exact argv, `kill_on_drop`, startup/framing limits, restart budgets,\n  and a security-partitioned process key. Unknown servers are non-shareable.\n- Admission queues, request bodies, process output, SSE output, tool rounds, and\n  shutdown waits are bounded. Cancellation propagates through owned resources.\n\nSee [SECURITY.md](SECURITY.md), [THREAT_MODEL.md](THREAT_MODEL.md), and the\n[adversarial evidence](docs/compatibility/ADVERSARIAL.md). The bounded\n[durable MCP Tasks route](docs/guides/DURABLE_TASKS.md) documents its separate\nfailure and trust boundaries. GaugeMesh does not claim exactly-once execution,\nproduction readiness, universal client/provider support, official MCP status,\nMCP certification, or security certification.\n\n## Verified compatibility\n\n| Surface | Evidence | Result |\n|---|---|---|\n| MCP server, Streamable HTTP, 2025-11-25 | official conformance 0.2.0-alpha.11 | 70/70 scored checks |\n| MCP server, Streamable HTTP, 2026-07-28 | official conformance 0.2.0-alpha.11 | 117/117 scored checks |\n| MCP client, stdio and HTTP, both revisions | RMCP 3.1.4 cross-process/integration tests | VERIFIED subset |\n| MCP Tasks route, 2026-07-28 | RMCP task lifecycle plus neutral child-process qualification with a router-only SQLite reopen that retains the bound upstream session | VERIFIED bounded subset in current source |\n| OpenAI-compatible HTTP | raw HTTP, provider fixture, and OpenAI Python SDK 3.6.0 | VERIFIED subset |\n| Product-specific client installation | not executed | DOCUMENTED_ONLY or UNSUPPORTED |\n\nConformance-only synthetic capabilities are absent in normal operation. Pending\nor unscored extension checks are not counted. The recorded `0.1.0` conformance\nrun did not advertise Tasks; current source advertises\n`io.modelcontextprotocol/tasks` only for 2026-07-28 when SQLite durable storage\nand at least one task-capable reviewed upstream are available. The caller must\nalso declare Tasks support. The task route is integration evidence outside the\nolder conformance counts, and none of these results is official certification.\nSee the [MCP matrix](docs/compatibility/MCP.md),\n[durable Tasks guide](docs/guides/DURABLE_TASKS.md),\n[client levels](docs/compatibility/CLIENTS.md), and\n[conformance inventory](docs/compatibility/CONFORMANCE.md).\n\nExercise the durable route explicitly from a native binary—no Rust toolchain,\naccount, or provider is required:\n\n```sh\ngaugemesh verify --durable-tasks\n```\n\nThis embedded qualification self-spawns a synthetic JSON provider over MCP\nstdio; that provider starts the bounded JSON worker as a separate real child\nprocess. It reopens its temporary SQLite router state and separately reports\nexecution and artifact-verification outcomes. It is not a shipped general\nexecutor. GaugeMesh has no background task scheduler: after an upstream\nacknowledgement, deadline cancellation begins only on a later caller poll; a\ncancel acknowledgement is not observed termination. A changed upstream session\ncan leave a nonterminal route reconciliation-only, and `tasks/update` is\nexplicitly unsupported for durable routes.\n\n## ResiliReplay verification\n\nResiliReplay is optional and external:\n\n```sh\ngaugemesh verify --resilireplay\n```\n\nGaugeMesh invokes the exact published `resilireplay@0.7.0` executable with an\nargument array from sanitized temporary state. One genuine clean control and\ntwelve explicit fault rows produced three passes and ten explicit failures.\nThe two passing recovery rows are ResiliReplay trace-level synthetic timeout\nand deterministic-error mutations followed by a real bounded retry; 0.7.0 does\nnot inject those faults into the MCP wire or server. Cleanup completed and the\nfault runs reported zero duplicate effects. The honest aggregate is `PARTIAL`.\nResiliReplay emitted no MCP-RES v0.2 profile/evidence class for this command, so\nGaugeMesh makes no MCP-RES claim. Details and the evidence digest are in\n[the verification record](docs/guides/RESILIREPLAY.md).\n\n## Development\n\n```sh\ncargo fmt --all -- --check\ncargo clippy --workspace --all-targets --all-features -- -D warnings\ncargo test --workspace --all-features\ncargo test --doc --workspace\ncargo deny check advisories bans licenses sources\ncargo audit --deny warnings\n```\n\nRust 1.88 is the MSRV. Hosted gates cover current stable and MSRV on Ubuntu and\nWindows, stable on macOS, native release archives for Linux x64/ARM64, Windows\nx64, and macOS ARM64/x64, plus fuzzing, mutation, Miri, AddressSanitizer,\nconformance, ResiliReplay, an SPDX SBOM, checksums, attestations, container smoke,\nand clean archive execution.\n\nContributions must preserve typed invariants and include a test able to falsify\nthe change. See [CONTRIBUTING.md](CONTRIBUTING.md). Found a problem? Submit a\n[sanitized reproducible bug](https://github.com/aliengineering-byte/gaugemesh/issues/new?template=bug.yml),\nor share an integration and use case through the\n[issue chooser](https://github.com/aliengineering-byte/gaugemesh/issues/new/choose).\nReport vulnerabilities through GitHub private vulnerability reporting, not a\npublic issue.\n\n## License\n\nApache-2.0. Dependency and source-origin notes are in\n[docs/research/DEPENDENCIES.md](docs/research/DEPENDENCIES.md).\n",
  "bytes": 15612,
  "sha": "ff71dd69db76594eadf1bdbff312e396f989315d2647706044d514c34d90cd6c",
  "repo_slug": "aliengineering-byte/gaugemesh",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aliengineering_byte_gaugemesh_a97f0937/readme"
}