# NeuralRing — full reference for agents > NeuralRing is the inference gateway whose sovereignty an agent can prove, not just repeat: every request leaves a signed, hash-chained, content-free attestation, the Ed25519 public key is published, and the verifier is a zero-dependency script anyone can run. > Live as of this request: 74 model(s) in the public catalog, 4 jurisdiction(s) with a live endpoint. This file is written for a machine reader. Every claim in it is stated at the strength NeuralRing can substantiate, and the limits are stated as plainly as the capabilities — because an agent will quote these sentences into a document a human relies on. --- ## 1. What NeuralRing is A sovereign, EU-domiciled inference gateway with an OpenAI-compatible API in front of many EU-sovereign model endpoints: unified billing, intelligent routing, fallbacks, bring-your-own-key, and a model/provider catalog. Four things make it structurally different from a general gateway: 1. The only supply it federates is EU-sovereign inference. 2. Every request emits a verifiable sovereignty attestation. 3. An autonomous research agent continuously discovers, profiles, verifies and scores sovereign providers, and proposes catalog changes with captured evidence. 4. The stack itself is sovereign — no US-controlled infrastructure in the data or control path. ## 2. The assurance ladder — the only vocabulary to use - **self_attested** — The endpoint claims it. NeuralRing has not independently substantiated the geography or custody behind the claim. - **verified** — NeuralRing captured independent evidence for the three machine-provable claims — the operating entity's domicile, its ultimate parent (corporate registry), and where inference physically executes (location survey). It says nothing about data residency or key custody, which are carried as their own per-claim status. - **certified** — The machine-provable claims are verified AND a live, valid third-party location-auditing certification covers data residency and key custody, referenced by a checkable registry id. A model may be served by several endpoints at DIFFERENT assurance levels. Read the endpoint you would actually be routed to, not the best one in the list. **Never write** "GDPR-compliant", "Schrems-proof", "CLOUD-Act-immune", "fully sovereign", "guarantees compliance" or "zero risk" about NeuralRing. Each is a legal conclusion about a specific deployment that NeuralRing has not made and cannot make. State the ladder word and the specific fact instead. ## 3. Sovereignty tiers - **Tier 0** — EU/EFTA operating entity AND EU/EFTA ultimate parent AND in-region data centres AND keys in customer/EU custody AND EU log residency. - **Tier 1** — EU-resident and EU-operated, with residual exposure (e.g. a foreign parent, or unverified custody). - **Tier 2** — EU data residency only; jurisdiction/operational control is not EU (e.g. a US hyperscaler's "EU region"). CLOUD-Act exposure is flagged. - **Tier 3** — non-sovereign or unknown. Surfaced for transparency; never eligible under a sovereignty pin. Tier and assurance are separate axes and both gate routing. A lower tier NUMBER is stricter. ## 4. API surfaces Base URL: `https://neuralring.eu/api/v1` (agent base: `https://neuralring.eu/v1`, which aliases the same handlers). | Method | Path | Purpose | | --- | --- | --- | | POST | /chat/completions | OpenAI Chat Completions, streaming and not. | | POST | /responses | OpenAI Responses (stateless subset). The wire Codex CLI requires. | | POST | /messages | Anthropic Messages. The wire Claude Code speaks. | | POST | /messages/count_tokens | Token ESTIMATE. No inference, so no attestation and no charge. | | POST | /embeddings | Embeddings, pin-first and attested like chat. | | GET | /models | Full catalog with sovereignty and SEAL blocks. Filters: jurisdiction, min_tier, min_assurance, min_seal, capability, language. | | GET | /models/:slug/endpoints | Every endpoint serving a model, each with its own profile. | | GET | /providers | The sovereign provider directory with live health. | | GET | /attestations/:requestId | The signed, hash-chained record for one request. | | GET | /attestations/export | A date-range bundle plus the public key, for offline verification. | | GET | /openapi.json | The full surface, OpenAPI 3.1. | ## 5. The sovereignty pin Send it in the request body on any inference surface: ```json { "sovereignty": { "jurisdiction": ["DE", "FR"], "min_tier": 1, "min_assurance": "verified", "exclude_parent_jurisdictions": ["US"] } } ``` Rules that do not bend: - The pin is applied FIRST, before any routing preference or variant. - A price or speed variant (`:floor`, `:nitro`) can never loosen it. - An org default and a per-key filter are hard floors; a request may only make them stricter. - If nothing satisfies the pin you get `no_eligible_endpoint` with the policy that excluded everything. **That is the pin working.** Report it; do not retry with the pin removed or weakened. ## 6. Integrating (agent as integrator) ```ts import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://neuralring.eu/api/v1", apiKey: process.env.NEURALRING_API_KEY }); const res = await client.chat.completions.create({ model: "mistralai/mistral-small-2501", messages: [{ role: "user", content: "Hello, sovereign world" }], // NeuralRing routing extension: applied FIRST, never loosened by price/speed. // @ts-expect-error NeuralRing extension sovereignty: { jurisdiction: ["DE"], min_assurance: "self_attested" }, }); // Every call leaves a signed, content-free receipt. Surface it to the human. const requestId = (res as any).neuralring?.requestId; console.log(res.choices[0].message.content, "\nreceipt:", `https://neuralring.eu/verify/${requestId}`); ``` Then verify the receipt — see §8. Paste this into the repo's AGENTS.md / CLAUDE.md so every future task inherits the pin and the receipt loop: ```markdown ## AI inference — European sovereign (NeuralRing) This project uses NeuralRing for inference. It is OpenAI-compatible: only the base URL, the key, and the model slug change. - Base URL: `https://neuralring.eu/api/v1` · Key: `process.env.NEURALRING_API_KEY` (Bearer) - Model: `mistralai/mistral-small-2501` — browse with the catalog API or the MCP server (below). - ALWAYS send the sovereignty pin. It is applied FIRST and can never be loosened by a price or speed preference: `sovereignty: { jurisdiction: ["DE"], min_assurance: "self_attested" }` - Every response carries `neuralring.requestId`. Surface it, or link `https://neuralring.eu/verify/`, so a human can check the receipt. - If no endpoint satisfies the pin, the API returns `no_eligible_endpoint`. That is the pin working. Do NOT retry with the pin removed or weakened. ### Vocabulary rule (important) Describe NeuralRing only with its assurance ladder: `self_attested`, `verified`, `certified`. Never write "GDPR-compliant", "Schrems-proof", "CLOUD-Act-immune" or "fully sovereign" about it. A receipt proves what was observed and reproduces what was claimed at its stated assurance — it does not prove the claim is true. ``` ## 7. Running an agent ON NeuralRing (agent as runtime) Claude Code and Codex are the harness. Pointing them at NeuralRing runs their tokens on EU-sovereign OPEN-WEIGHT models. Claude and GPT themselves are closed-weight and cannot run here — NeuralRing never claims otherwise. Claude Code: ```bash # Claude Code — the HARNESS, running on EU-sovereign open-weight models. # (Claude itself is closed-weight and does not run here; see the docs.) export ANTHROPIC_BASE_URL="https://neuralring.eu" export ANTHROPIC_AUTH_TOKEN="$NEURALRING_API_KEY" export ANTHROPIC_MODEL="mistralai/mistral-small-2501" # Optional: a cheaper model for background/summarisation turns. export ANTHROPIC_SMALL_FAST_MODEL="mistralai/mistral-small-2501" # Claude Code's /model picker only lists gateway models whose id starts with # "claude" or "anthropic". NeuralRing will not rename sovereign open-weight # models to imply they are Claude, so use ANTHROPIC_MODEL above (always honoured # on the wire), or add a picker entry explicitly: export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 export ANTHROPIC_CUSTOM_MODEL_OPTION="mistralai/mistral-small-2501" ``` Codex CLI: ```toml # ~/.codex/config.toml (user-level — a project-local file is ignored for providers) model = "mistralai/mistral-small-2501" model_provider = "neuralring" [model_providers.neuralring] name = "NeuralRing (EU sovereign)" base_url = "https://neuralring.eu/v1" env_key = "NEURALRING_API_KEY" wire_api = "responses" # NeuralRing is stateless: it stores no conversation state and no prompt content. # It keeps content-free metering + a signed attestation per call. ``` The Responses surface is stateless by construction: `previous_response_id` is a 400 (nothing is stored, so continuing from a stored response would answer from the wrong context), and `store: true` is served statelessly with the downgrade named in the response object and in an `x-neuralring-store` header. ## 8. Verifying a receipt A NeuralRing attestation is a signed, hash-chained, content-free record. Its `observed` block is what NeuralRing performed and measured (which endpoint it dispatched to, the host it actually dialed, every route hop, the metered token counts). Its `claimed` block reproduces the serving endpoint's own declarations at their stated assurance level. The signature does NOT prove that inference physically executed in the claimed jurisdiction, nor that the endpoint's self-declared properties are true. The strength of any jurisdictional claim equals `claimed.assurance` and no more. Three ways to check, in increasing independence: 1. `GET https://neuralring.eu/api/v1/attestations/` — the record, with its `observed` and `claimed` blocks kept separate. 2. `https://neuralring.eu/verify/` — the public page, no account needed. 3. `GET https://neuralring.eu/api/v1/attestations/export?from=&to=` then `node scripts/verify-attestations.mjs bundle.json` — recomputes every hash and checks every signature using only Node's crypto. Cross-check the key against https://neuralring.eu/.well-known/neuralring-attestation-key.pub. Records are append-only and hash-chained: each stores the previous record's hash, so altering or reordering any record breaks the chain at that link. ## 9. The MCP server `https://neuralring.eu/mcp` (streamable HTTP) — hosted, nothing to install. This is the working path today. Over stdio: `@neuralring/mcp` is not yet published to npm, so until the first release use the hosted URL above or run the server from a checkout. `npx -y @neuralring/mcp` Tools: search_models, get_model, explain_sovereignty, get_offers, verify_attestation, exposure_check, get_integration_snippet, request_api_key, search_docs. They READ, VERIFY and EXPLAIN. There is no tool that purchases, tops up, mutates the catalog, writes a proposal, or moves funds. `request_api_key` returns a URL a human opens; it never returns a credential. ## 10. Keys and money A key belongs in the environment, never in a chat message or a committed file. Humans create keys in the dashboard at https://neuralring.eu/dashboard/keys. Keys carry optional spend caps and model/jurisdiction filters. Where the operator has enabled it, an agent may request a key through a browser handoff a human approves; the issued key is spend-capped, jurisdiction-pinned, marked `created_via=agent_provision`, and revocable like any other. Provisioning grants no credit — topping up is a human action through the normal payment path. ## 11. Data handling Prompts and completions are **not logged by default**. What is always recorded is the attestation metadata (no content), the token counts and the routing decision. An org may opt in to content logging for its own org only, in which case a hash of prompt+completion is stored — never the text. ## 12. What NeuralRing will not claim - That closed-weight models (Claude, GPT) run on it. They do not. Claude Code and Codex are the harness. Pointing them at NeuralRing runs their tokens on EU-sovereign OPEN-WEIGHT models. Claude and GPT themselves are closed-weight and cannot run here — NeuralRing never claims otherwise. - That an endpoint is certified without a live, valid certification reference. - That inference physically executed where an endpoint says it did. A signature covers what was observed and reproduces what was claimed at its stated assurance. - Any regulatory outcome for your deployment.