{"slug": "show-hn-vyral-portable-contracts-for-data-retrieval-durable-work-and-mcp", "title": "Show HN: Vyral – Portable contracts for data, retrieval, durable work, and MCP", "summary": "Vyral, an open-source, local-first contract layer and runtime for applications needing records, retrieval, durable work, and agent-facing AI, has been released. It enables provider-portable capabilities across SQLite, Postgres/pgvector, Azure, AWS, Google Cloud, Cloudflare, and Temporal without changing application code. The project includes a versioned qualification matrix and conformance fixtures to make adapter behavior explicit.", "body_md": "**Own the contract layer.**\n\nProvider-portable canonical data, retrieval, durable execution, and agent-facing AI.\n\n[Quick start](#quick-start) ·\n[Capabilities](#core-capabilities) ·\n[MCP](#stateless-mcp) ·\n[Evidence](#adapter-qualification) ·\n[Documentation](#documentation) ·\n[Contributing](/Univeracity/vyral/blob/main/CONTRIBUTING.md)\n\nVyral is an open-source, local-first contract layer and runtime for applications\nthat own canonical data and need **records and objects**, **retrieval and RAG**,\n**durable work**, and **agent-facing AI**. It keeps those capabilities behind\nstable, application-owned contracts instead of vendor SDKs.\n\nStart on a laptop with one command. When economics, features, policy, or scale change, adapters can move individual capabilities to SQLite, Postgres/pgvector, Azure, AWS, Google Cloud, Cloudflare, Temporal, and other providers without changing application code. Language-neutral conformance fixtures and a versioned qualification matrix make adapter behavior explicit instead of assumed.\n\nTry the end-to-end local path from a source checkout:\n\n```\n./scripts/vyral\n```\n\nThis is the only command required for the local demonstration. With Python 3.10\nor newer—and no package installation, .NET SDK, container runtime, cloud\naccount, external service, or model download—it runs lexical retrieval with\ncitations, admits durable work, reopens the runtime, and completes the\npreserved run. State remains inspectable under `./.vyral/quickstart`\n\n.\n\nCreate an editable application when you are ready to build:\n\n```\n./scripts/vyral init\n./scripts/vyral run ./vyral_app.py\n```\n\nThe runtime distribution and command are both `vyral`\n\n; `vyral-runtime`\n\nremains\na compatibility command alias. Use `./scripts/vyral inspect`\n\nto explain the local\nproviders and limitations. Windows users can invoke the source launcher with\n`python scripts/vyral`\n\n. Installation, custom state paths, JSON output, reset,\nand server instructions are in the\n[Python runtime guide](/Univeracity/vyral/blob/main/runtimes/python).\n\n| You need… | Start here |\n|---|---|\n| Try Vyral locally |\n|\n\n[Retrieval guide](/Univeracity/vyral/blob/main/docs/guides/source-native-retrieval.md)[Python runtime](/Univeracity/vyral/blob/main/runtimes/python)[Runtimes and clients](#choose-a-runtime-or-client)[Execution runtime](#execution-runtime)[Qualification matrix](/Univeracity/vyral/blob/main/qualification/README.md)AI applications often start with a simple local path, then accumulate provider assumptions: storage shapes, search semantics, object layouts, embedding APIs, quotas, auth, and SDK-specific envelopes. A provider change becomes a product rewrite rather than an infrastructure decision.\n\nVyral keeps the capability model application-owned:\n\n**Records**— ids, partition keys, metadata, content, sources, vectors, and etags** Objects**— large immutable payloads and manifests outside the record index** Retrieval**— source-native, lexical, vector, and hybrid search, profiles, and evaluation** RAG**— deterministic chunk plans, dry-run/commit, manifests, context, and citations** Agent-facing AI**— one envelope for local, CLI, ONNX-backed, and remote capabilities** Execution**— durable runs and plugins with local and provider-backed adapters** Evidence**— readiness, traces, conformance suites, and qualification levels\n\nVyral is most useful when an application needs to cross one or more provider seams without giving those providers ownership of its data and execution semantics.\n\nVyral does not assume vector search is always the answer. For current, structured sources that an application can safely access, direct source search is often the simplest first path. Indexed lexical, vector, hybrid, and reranked retrieval remain available when corpus shape and measured quality justify them.\n\nVyral is Apache-2.0 software with independently evidenced capabilities. Local\nrecords, objects, retrieval, RAG, and the .NET contract surface are the primary\npaths; other capabilities carry their own boundary below. See the\n[stability policy](/Univeracity/vyral/blob/main/docs/reference/stability.md) for compatibility commitments.\n\n| Surface | Current capability |\n|---|---|\n| .NET local server, SQLite, retrieval, and RAG | Primary local implementation |\n| Python and JavaScript HTTP clients | Implemented and tested against the public SDK catalog |\n| Python-native embedded runtime and REST/MCP host | Prototype; clean-artifact qualified on Python 3.10–3.12 across Linux, macOS, and Windows; independent security review remains |\n| Source-native ripgrep integration | Experimental; bounded exact-literal search over authorized code and Markdown, outside the stable wire/MCP contract |\nStateless MCP `2026-07-28` endpoint |\nPreview; opt-in and REST-backed |\n| Local SQLite, Azure, and Google execution | Local reference path; Azure and Google execution are live qualified |\n| Temporal, pgvector, and Cloudflare adapters | Preview or prototype; live qualification is opt-in |\n\nPackage availability does not itself establish a service-level commitment. The\n[qualification report](/Univeracity/vyral/blob/main/qualification/adapter-qualification.json) is the source\nof truth for recorded evidence.\n\nTo exercise the server boundary instead, start the .NET host from the repository root:\n\n```\nscripts/start-local-server.sh\n```\n\nIt listens on `http://127.0.0.1:5220`\n\nand writes local state beneath `.vyral/`\n\n.\nRun either HTTP client example to create a collection, store three documents,\nretrieve lexical context without embeddings, and print citations:\n\n```\npython3 examples/python/rag_quickstart.py\nnode examples/javascript/rag-quickstart.mjs\n```\n\nSet `VYRAL_URL`\n\nto use a different host. More complete retrieval, GraphRAG, AI,\nand execution examples live in [examples](/Univeracity/vyral/blob/main/examples) and [samples](/Univeracity/vyral/blob/main/samples).\n\nThe server image is non-root, shell-free, and compatible with a read-only root filesystem. This local command keeps state in a Docker-managed volume:\n\n```\ndocker build -t vyral-server .\ndocker volume create vyral-data\nexport VYRAL_API_KEY=\"$(openssl rand -hex 32)\"\ndocker run --rm \\\n  --publish 127.0.0.1:8080:8080 \\\n  --read-only \\\n  --mount type=volume,source=vyral-data,target=/app/.vyral \\\n  --cap-drop ALL \\\n  --security-opt no-new-privileges=true \\\n  --pids-limit 256 \\\n  --env VYRAL_API_KEY \\\n  vyral-server\n```\n\nCanonicalStore routes are disabled in the image unless their identity policies\nare explicitly configured. The image requires an API key before it starts;\nhealth and readiness remain public while data-plane routes require\n`X-Vyral-Api-Key`\n\nor `Authorization: Bearer …`\n\n. This key establishes one\napplication trust boundary, not multi-tenant authorization. Shared deployments\nalso need TLS, rate limits, authenticated ingress, and deployment-specific\nidentity policy. See the [CanonicalStore guide](/Univeracity/vyral/blob/main/docs/concepts/canonical-store.md)\nand the [deployment guide](/Univeracity/vyral/blob/main/deploy).\n\nThe hardened immutable server image is\n`ghcr.io/univeracity/vyral-server:0.3.1`\n\n; use it with the same API-key and\nruntime restrictions shown above.\n\n| Goal | Entry point |\n|---|---|\n| Run the full .NET server and provider adapters | `src/Vyral.Server` and packages under `src/` |\n| Run Vyral in a Python process | `vyral` in `runtimes/python` |\n| Host REST and MCP from Python | `vyral[server]` |\n| Call a running host from Python | `vyral-client` in `clients/python` |\n| Call a running host from JavaScript | `vyral-client` in `clients/javascript` |\n| Implement an external worker in Go | `clients/go` |\n\nThe Python runtime is a peer implementation, not a wrapper around .NET. The Python and .NET runtimes share wire contracts and conformance fixtures, but their database files and migration histories are private implementation details. Move data through documented exports and envelopes; do not copy a SQLite database between runtimes.\n\nOpenAPI is the wire authority. The\n[public SDK catalog](/Univeracity/vyral/blob/main/contracts/public-sdk-surface.json) maps stable operation\nIDs to the Python and JavaScript clients, generated types, MCP surfaces, and\nruntime implementations.\n\n| Area | What the contract covers |\n|---|---|\n| Records and objects | Partitioned records, metadata, vectors, sources, etags, batches, immutable objects, manifests, and snapshots |\n| Retrieval | Structured filters, lexical/vector/hybrid search, fusion, profiles, reranking, diagnostics, and evaluation |\n| RAG | Deterministic ingestion, dry-run and durable admission, citations, bounded context, prompts, and GraphRAG expansion |\n| Graphs | Import/export, preflight, inspection, doctor, bounded traversal, assertions, reviews, and projections |\n| AI runs | Model discovery, capability guidance, extraction, embedding, reranking, quotas, artifacts, and normalized status |\n| Durable execution | Idempotent admission, retries, cancellation, timers, waits, checkpoints, artifacts, leases, plugins, and external workers |\n| Operations | Health, readiness, traces, redacted diagnostics, conformance, qualification receipts, and release evidence |\n\nThe REST host exposes the complete contract at\n`/openapi/vyral.json`\n\n. Detailed request shapes belong in OpenAPI and the client\ndocumentation rather than being duplicated here.\n\nVyral implements the MCP `2026-07-28`\n\nstateless request/response protocol at\nthe opt-in `POST /mcp`\n\nendpoint. Each request carries its version, routing,\ncapability, and authorization context in headers. The server creates no MCP\nsession, so a gateway can route and authorize requests before sending any call\nto any healthy instance behind an ordinary load balancer.\n\nEnable the default read/resource catalog on the .NET host:\n\n```\nMcp__Enabled=true dotnet run --project src/Vyral.Server/Vyral.Server.csproj\n```\n\nWrite tools are disabled by default. Enable them by semantic operation ID, for example:\n\n```\nMcp__Enabled=true \\\nMcp__EnabledOperationIds__0=startEmbeddingJob \\\ndotnet run --project src/Vyral.Server/Vyral.Server.csproj\n```\n\nLong-running MCP tools return durable task envelopes while Vyral's execution runtime remains the run authority. Routing headers are never treated as authorization claims, and binary artifact upload remains REST-only.\n\nRun the frozen official profile plus Vyral's multi-instance, failover, task, policy, and telemetry fixtures with:\n\n```\nscripts/verify-mcp-conformance.sh\n```\n\nThe packaged Python host runs the same frozen official requirements profile in the Python runtime qualification workflow; its conformance fixtures are enabled only for that gate.\n\nSee the request boundary work across two independent local instances:\n\n```\npython3 examples/python/stateless_mcp_round_robin.py\n```\n\nThe [gateway guide](/Univeracity/vyral/blob/main/docs/guides/stateless-mcp.md) covers deployment checks. The\n[stateless MCP design](/Univeracity/vyral/blob/main/design/public-sdk-surface-and-stateless-mcp.md) defines\nrouting, catalog policy, security boundaries, and acceptance criteria.\n\nThe default local shape uses SQLite for records and traces and the filesystem for objects. Deployment can select provider adapters without changing consumer requests:\n\n| Capability | Local default | Available adapters |\n|---|---|---|\n| Records | SQLite | Firestore, AlloyDB/pgvector, Azure Cosmos DB, DynamoDB |\n| Objects | Filesystem | Google Cloud Storage, Cloudflare R2, Azure Blob Storage, S3 |\n| Retrieval | SQLite/local providers | pgvector and provider-shaped adapters |\n| Traces | SQLite | Firestore and deployment-specific sinks |\n\nExercise the portable data boundary without cloud credentials:\n\n```\npython3 examples/python/canonical_store_cutover.py\n```\n\nThe [portable cutover guide](/Univeracity/vyral/blob/main/docs/guides/portable-cutovers.md) extends that\nlocal proof into provider preflight, shadowing, cutover, rollback, and retained\nevidence.\n\nRetrieval supports structured filters, lexical, vector, and hybrid modes; configurable fusion and reranking; reusable profiles; and evaluation receipts. The deterministic local embedding provider is for mechanics and repeatability, not semantic quality. ONNX and provider-backed models require explicit model or credential configuration.\n\nRAG ingestion separates planning from commit, persists manifests, and admits large mutations through durable execution. RAG context responses preserve citations, source spans, truncation diagnostics, and stable context hashes.\n\nSee [the consumer handoff](/Univeracity/vyral/blob/main/docs/guides/consumer-handoff.md) for configuration and failure\ninterpretation, and [the examples](/Univeracity/vyral/blob/main/examples) for working retrieval recipes.\n\n`ICanonicalStore`\n\nis Vyral's strong-storage profile for canonical application\nstate. A tenant-scoped transaction atomically commits documents, immutable\nrevisions, uniqueness or command fences, outbox events, and its idempotency\nreceipt—or commits none of them.\n\nLocal SQLite, PostgreSQL, and MySQL 8/InnoDB implementations are included.\nConsumers retain ownership of document schemas, transformations, projections,\nand migrations; CanonicalStore does not promise portable arbitrary SQL or\nprovider-specific query behavior. See the [CanonicalStore guide](/Univeracity/vyral/blob/main/docs/concepts/canonical-store.md)\nfor the transaction contract, identity policy, export/restore flow, and\ndeployment configuration.\n\nVyral imports, exports, and traverses\n[ROMAN-compatible graph envelopes](/Univeracity/vyral/blob/main/docs/roman.md) through ordinary record\ncollections. Nodes, edges, source-grounded assertions, reviews, and projections\nremain portable records rather than requiring a separate graph database.\n\nGraph import has a non-mutating preflight. Inspection and doctor operations report graph health and seed coverage. GraphRAG starts with retrieved records, resolves their graph-node identifiers, performs a bounded traversal, and returns a projection with provenance and budget diagnostics. Relationships add context; they do not replace retrieved source evidence.\n\nAI runs normalize model discovery, capability guidance, request status, artifacts, traces, and quota reporting across local, CLI, ONNX, and remote providers. Provider-specific behavior stays behind adapter boundaries and is surfaced through readiness and qualification evidence rather than silent fallback.\n\nLive credentials and model assets are always opt-in. Local development should use deterministic fixtures or explicitly installed untracked model files.\n\nThe execution contract covers admission, status, history, events, progress, retries, cancellation, timers, waits, checkpoints, artifacts, concurrency keys, maintenance, and plugin discovery.\n\nVyral uses two canonical mutation shapes:\n\n- synchronous operations return only after the requested effect is complete;\n- receipt-bound asynchronous operations durably admit work and return a run or job receipt whose status can be queried independently.\n\nThe local SQLite runtime is the reference implementation. Azure Durable, AWS, Google Cloud Tasks, and Temporal adapters implement different subsets and carry separate qualification evidence. External workers use leases, heartbeats, cancellation, and token-safe artifact transport without owning the execution authority.\n\nVyral can also sit inside an existing orchestrator without replacing it. The\n[Prefect receipt-flow example](/Univeracity/vyral/blob/main/examples#prefect-composition) lets\nPrefect own schedules, task retries, and operator visibility while Vyral owns\ndurable admission, status, and results. It is a composition recipe, not a\nPrefect adapter or qualification claim.\n\nStart with the [execution design](/Univeracity/vyral/blob/main/design/execution-runtime.md),\n[admission contract](/Univeracity/vyral/blob/main/design/admission-contract.md),\n[plugin authoring guide](/Univeracity/vyral/blob/main/design/execution-runtime-plugin-authoring.md), and\n[current limitations](/Univeracity/vyral/blob/main/docs/reference/execution-runtime-limitations.md).\n\n| Area | Current posture |\n|---|---|\n| Local SQLite records, objects, retrieval, and execution | Reference path; deterministic conformance |\n| PostgreSQL/pgvector and CanonicalStore | Implemented; live deployment evidence remains environment-specific |\n| Azure Durable Functions execution | Live qualified; Azure storage adapters retain their separate preview posture |\n| AWS storage and execution | Live qualified for isolated S3, DynamoDB, and SQS; managed OpenSearch remains subject to end-user validation |\n| Google execution | Live qualified; other Google adapters retain their separate qualification posture |\n| Temporal coordinator and projection | Prototype; disposable and operator-provisioned qualification gates |\n| Cloudflare R2 | Preview object-store adapter |\n\nAn adapter is `live_qualified`\n\nonly when the versioned\n[qualification matrix](/Univeracity/vyral/blob/main/qualification/README.md) records the required evidence.\nThe matrix is generated from the canonical JSON report; availability, a\nsuccessful build, or a package version alone does not establish that claim.\nAdapter authors should begin with the\n[adapter contributor guide](/Univeracity/vyral/blob/main/docs/contributing/adapter-contributor.md).\n\n```\nsrc/           .NET contracts, runtimes, server, and provider adapters\nclients/       Python and JavaScript HTTP SDKs; Go external-worker client\nruntimes/      Peer runtime implementations, currently Python\ncontracts/     OpenAPI-derived public SDK catalog and JSON schemas\nconformance/   Language-neutral cross-runtime fixtures\nexamples/      Short HTTP client recipes\nsamples/       Runnable .NET and execution examples\ntests/         Unit, integration, conformance, and adapter suites\nqualification/ Versioned adapter qualification report and policy\ndesign/        Contract and runtime designs\ndocs/          User, contributor, maintainer, and reference documentation\ndeploy/        Deployment preflights and qualification shapes\npackaging/     Shared package landing-page inputs\nscripts/       Local start, generation, verification, and release gates\n```\n\nThe ordinary deterministic checks are:\n\n```\nscripts/run-dotnet-tests.sh Vyral.sln\n\nnpm ci --ignore-scripts --prefix clients/javascript\nnpm test --prefix clients/javascript\n\npython3 -m pip install \\\n  --editable 'clients/python[typecheck]' \\\n  --editable 'runtimes/python[dev]'\npython3 -m unittest discover -s clients/python/tests -p 'test_*.py'\nscripts/verify-python-runtime.sh\n```\n\nContract generation and repository-policy checks run in CI. Before treating a commit as releasable, run the larger artifact and consumer gate:\n\n```\nscripts/verify-release-artifacts.sh\n```\n\nLive provider gates are separate, explicit, and credential-bearing. They are\nnot part of the default local test suite. Release and publication procedures\nare documented in the [release process](/Univeracity/vyral/blob/main/docs/maintainers/releasing.md).\n\n| Topic | Document |\n|---|---|\n| Documentation index |\n|\n\n[Consumer handoff](/Univeracity/vyral/blob/main/docs/guides/consumer-handoff.md)[Stability policy](/Univeracity/vyral/blob/main/docs/reference/stability.md)[SECURITY.md](/Univeracity/vyral/blob/main/SECURITY.md)[design/public-sdk-surface-and-stateless-mcp.md](/Univeracity/vyral/blob/main/design/public-sdk-surface-and-stateless-mcp.md)[runtimes/python/README.md](/Univeracity/vyral/blob/main/runtimes/python/README.md)and[design/python-runtime.md](/Univeracity/vyral/blob/main/design/python-runtime.md)[Extropic execution guide](/Univeracity/vyral/blob/main/docs/guides/extropic-execution.md)[CanonicalStore guide](/Univeracity/vyral/blob/main/docs/concepts/canonical-store.md)[design/execution-runtime.md](/Univeracity/vyral/blob/main/design/execution-runtime.md)[Adapter contributor guide](/Univeracity/vyral/blob/main/docs/contributing/adapter-contributor.md)[deploy/README.md](/Univeracity/vyral/blob/main/deploy/README.md)[ROADMAP.md](/Univeracity/vyral/blob/main/ROADMAP.md)- Vyral is pre-1.0; preview contracts can still change under the documented stability policy.\n- The Python peer runtime remains a prototype until its remaining promotion evidence and independent review are complete.\n- Provider behavior is limited to the portable contract; provider-native features may require application-owned extensions.\n- Local deterministic embeddings validate mechanics, not semantic quality.\n- Live provider qualification requires operator-owned infrastructure, least-privilege credentials, and explicit execution.\n- CanonicalStore is intentionally narrower than a general relational database.\n- MCP is opt-in, and write tools require an explicit allowlist.\n\nRead [CONTRIBUTING.md](/Univeracity/vyral/blob/main/CONTRIBUTING.md), the\n[code of conduct](/Univeracity/vyral/blob/main/CODE_OF_CONDUCT.md), and the relevant contract or adapter\ndesign before proposing a change. Public behavior should be represented in\nOpenAPI, the SDK catalog, conformance fixtures, and qualification evidence—not\nonly in one implementation.\n\nVyral is licensed under [Apache License 2.0](/Univeracity/vyral/blob/main/LICENSE). Third-party notices and\nproject trademark guidance are in [THIRD-PARTY-NOTICES.md](/Univeracity/vyral/blob/main/THIRD-PARTY-NOTICES.md)\nand [TRADEMARKS.md](/Univeracity/vyral/blob/main/TRADEMARKS.md).\n\nA [Univeracity](https://univeracity.com) project ·\n[openvyral.com](https://openvyral.com)", "url": "https://wpnews.pro/news/show-hn-vyral-portable-contracts-for-data-retrieval-durable-work-and-mcp", "canonical_source": "https://github.com/Univeracity/vyral", "published_at": "2026-08-18 06:04:37+00:00", "updated_at": "2026-08-18 06:10:52.877465+00:00", "lang": "en", "topics": ["ai-infrastructure", "developer-tools", "ai-agents", "generative-ai"], "entities": ["Vyral", "SQLite", "Postgres", "Azure", "AWS", "Google Cloud", "Cloudflare", "Temporal"], "alternates": {"html": "https://wpnews.pro/news/show-hn-vyral-portable-contracts-for-data-retrieval-durable-work-and-mcp", "markdown": "https://wpnews.pro/news/show-hn-vyral-portable-contracts-for-data-retrieval-durable-work-and-mcp.md", "text": "https://wpnews.pro/news/show-hn-vyral-portable-contracts-for-data-retrieval-durable-work-and-mcp.txt", "jsonld": "https://wpnews.pro/news/show-hn-vyral-portable-contracts-for-data-retrieval-durable-work-and-mcp.jsonld"}}