# Show HN: Vyral – Portable contracts for data, retrieval, durable work, and MCP

> Source: <https://github.com/Univeracity/vyral>
> Published: 2026-08-18 06:04:37+00:00

**Own the contract layer.**

Provider-portable canonical data, retrieval, durable execution, and agent-facing AI.

[Quick start](#quick-start) ·
[Capabilities](#core-capabilities) ·
[MCP](#stateless-mcp) ·
[Evidence](#adapter-qualification) ·
[Documentation](#documentation) ·
[Contributing](/Univeracity/vyral/blob/main/CONTRIBUTING.md)

Vyral is an open-source, local-first contract layer and runtime for applications
that own canonical data and need **records and objects**, **retrieval and RAG**,
**durable work**, and **agent-facing AI**. It keeps those capabilities behind
stable, application-owned contracts instead of vendor SDKs.

Start 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.

Try the end-to-end local path from a source checkout:

```
./scripts/vyral
```

This is the only command required for the local demonstration. With Python 3.10
or newer—and no package installation, .NET SDK, container runtime, cloud
account, external service, or model download—it runs lexical retrieval with
citations, admits durable work, reopens the runtime, and completes the
preserved run. State remains inspectable under `./.vyral/quickstart`

.

Create an editable application when you are ready to build:

```
./scripts/vyral init
./scripts/vyral run ./vyral_app.py
```

The runtime distribution and command are both `vyral`

; `vyral-runtime`

remains
a compatibility command alias. Use `./scripts/vyral inspect`

to explain the local
providers and limitations. Windows users can invoke the source launcher with
`python scripts/vyral`

. Installation, custom state paths, JSON output, reset,
and server instructions are in the
[Python runtime guide](/Univeracity/vyral/blob/main/runtimes/python).

| You need… | Start here |
|---|---|
| Try Vyral locally |
|

[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.

Vyral keeps the capability model application-owned:

**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

Vyral 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.

Vyral 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.

Vyral is Apache-2.0 software with independently evidenced capabilities. Local
records, objects, retrieval, RAG, and the .NET contract surface are the primary
paths; other capabilities carry their own boundary below. See the
[stability policy](/Univeracity/vyral/blob/main/docs/reference/stability.md) for compatibility commitments.

| Surface | Current capability |
|---|---|
| .NET local server, SQLite, retrieval, and RAG | Primary local implementation |
| Python and JavaScript HTTP clients | Implemented and tested against the public SDK catalog |
| 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 |
| Source-native ripgrep integration | Experimental; bounded exact-literal search over authorized code and Markdown, outside the stable wire/MCP contract |
Stateless MCP `2026-07-28` endpoint |
Preview; opt-in and REST-backed |
| Local SQLite, Azure, and Google execution | Local reference path; Azure and Google execution are live qualified |
| Temporal, pgvector, and Cloudflare adapters | Preview or prototype; live qualification is opt-in |

Package availability does not itself establish a service-level commitment. The
[qualification report](/Univeracity/vyral/blob/main/qualification/adapter-qualification.json) is the source
of truth for recorded evidence.

To exercise the server boundary instead, start the .NET host from the repository root:

```
scripts/start-local-server.sh
```

It listens on `http://127.0.0.1:5220`

and writes local state beneath `.vyral/`

.
Run either HTTP client example to create a collection, store three documents,
retrieve lexical context without embeddings, and print citations:

```
python3 examples/python/rag_quickstart.py
node examples/javascript/rag-quickstart.mjs
```

Set `VYRAL_URL`

to use a different host. More complete retrieval, GraphRAG, AI,
and execution examples live in [examples](/Univeracity/vyral/blob/main/examples) and [samples](/Univeracity/vyral/blob/main/samples).

The 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:

```
docker build -t vyral-server .
docker volume create vyral-data
export VYRAL_API_KEY="$(openssl rand -hex 32)"
docker run --rm \
  --publish 127.0.0.1:8080:8080 \
  --read-only \
  --mount type=volume,source=vyral-data,target=/app/.vyral \
  --cap-drop ALL \
  --security-opt no-new-privileges=true \
  --pids-limit 256 \
  --env VYRAL_API_KEY \
  vyral-server
```

CanonicalStore routes are disabled in the image unless their identity policies
are explicitly configured. The image requires an API key before it starts;
health and readiness remain public while data-plane routes require
`X-Vyral-Api-Key`

or `Authorization: Bearer …`

. This key establishes one
application trust boundary, not multi-tenant authorization. Shared deployments
also need TLS, rate limits, authenticated ingress, and deployment-specific
identity policy. See the [CanonicalStore guide](/Univeracity/vyral/blob/main/docs/concepts/canonical-store.md)
and the [deployment guide](/Univeracity/vyral/blob/main/deploy).

The hardened immutable server image is
`ghcr.io/univeracity/vyral-server:0.3.1`

; use it with the same API-key and
runtime restrictions shown above.

| Goal | Entry point |
|---|---|
| Run the full .NET server and provider adapters | `src/Vyral.Server` and packages under `src/` |
| Run Vyral in a Python process | `vyral` in `runtimes/python` |
| Host REST and MCP from Python | `vyral[server]` |
| Call a running host from Python | `vyral-client` in `clients/python` |
| Call a running host from JavaScript | `vyral-client` in `clients/javascript` |
| Implement an external worker in Go | `clients/go` |

The 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.

OpenAPI is the wire authority. The
[public SDK catalog](/Univeracity/vyral/blob/main/contracts/public-sdk-surface.json) maps stable operation
IDs to the Python and JavaScript clients, generated types, MCP surfaces, and
runtime implementations.

| Area | What the contract covers |
|---|---|
| Records and objects | Partitioned records, metadata, vectors, sources, etags, batches, immutable objects, manifests, and snapshots |
| Retrieval | Structured filters, lexical/vector/hybrid search, fusion, profiles, reranking, diagnostics, and evaluation |
| RAG | Deterministic ingestion, dry-run and durable admission, citations, bounded context, prompts, and GraphRAG expansion |
| Graphs | Import/export, preflight, inspection, doctor, bounded traversal, assertions, reviews, and projections |
| AI runs | Model discovery, capability guidance, extraction, embedding, reranking, quotas, artifacts, and normalized status |
| Durable execution | Idempotent admission, retries, cancellation, timers, waits, checkpoints, artifacts, leases, plugins, and external workers |
| Operations | Health, readiness, traces, redacted diagnostics, conformance, qualification receipts, and release evidence |

The REST host exposes the complete contract at
`/openapi/vyral.json`

. Detailed request shapes belong in OpenAPI and the client
documentation rather than being duplicated here.

Vyral implements the MCP `2026-07-28`

stateless request/response protocol at
the opt-in `POST /mcp`

endpoint. Each request carries its version, routing,
capability, and authorization context in headers. The server creates no MCP
session, so a gateway can route and authorize requests before sending any call
to any healthy instance behind an ordinary load balancer.

Enable the default read/resource catalog on the .NET host:

```
Mcp__Enabled=true dotnet run --project src/Vyral.Server/Vyral.Server.csproj
```

Write tools are disabled by default. Enable them by semantic operation ID, for example:

```
Mcp__Enabled=true \
Mcp__EnabledOperationIds__0=startEmbeddingJob \
dotnet run --project src/Vyral.Server/Vyral.Server.csproj
```

Long-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.

Run the frozen official profile plus Vyral's multi-instance, failover, task, policy, and telemetry fixtures with:

```
scripts/verify-mcp-conformance.sh
```

The 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.

See the request boundary work across two independent local instances:

```
python3 examples/python/stateless_mcp_round_robin.py
```

The [gateway guide](/Univeracity/vyral/blob/main/docs/guides/stateless-mcp.md) covers deployment checks. The
[stateless MCP design](/Univeracity/vyral/blob/main/design/public-sdk-surface-and-stateless-mcp.md) defines
routing, catalog policy, security boundaries, and acceptance criteria.

The default local shape uses SQLite for records and traces and the filesystem for objects. Deployment can select provider adapters without changing consumer requests:

| Capability | Local default | Available adapters |
|---|---|---|
| Records | SQLite | Firestore, AlloyDB/pgvector, Azure Cosmos DB, DynamoDB |
| Objects | Filesystem | Google Cloud Storage, Cloudflare R2, Azure Blob Storage, S3 |
| Retrieval | SQLite/local providers | pgvector and provider-shaped adapters |
| Traces | SQLite | Firestore and deployment-specific sinks |

Exercise the portable data boundary without cloud credentials:

```
python3 examples/python/canonical_store_cutover.py
```

The [portable cutover guide](/Univeracity/vyral/blob/main/docs/guides/portable-cutovers.md) extends that
local proof into provider preflight, shadowing, cutover, rollback, and retained
evidence.

Retrieval 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.

RAG 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.

See [the consumer handoff](/Univeracity/vyral/blob/main/docs/guides/consumer-handoff.md) for configuration and failure
interpretation, and [the examples](/Univeracity/vyral/blob/main/examples) for working retrieval recipes.

`ICanonicalStore`

is Vyral's strong-storage profile for canonical application
state. A tenant-scoped transaction atomically commits documents, immutable
revisions, uniqueness or command fences, outbox events, and its idempotency
receipt—or commits none of them.

Local SQLite, PostgreSQL, and MySQL 8/InnoDB implementations are included.
Consumers retain ownership of document schemas, transformations, projections,
and migrations; CanonicalStore does not promise portable arbitrary SQL or
provider-specific query behavior. See the [CanonicalStore guide](/Univeracity/vyral/blob/main/docs/concepts/canonical-store.md)
for the transaction contract, identity policy, export/restore flow, and
deployment configuration.

Vyral imports, exports, and traverses
[ROMAN-compatible graph envelopes](/Univeracity/vyral/blob/main/docs/roman.md) through ordinary record
collections. Nodes, edges, source-grounded assertions, reviews, and projections
remain portable records rather than requiring a separate graph database.

Graph 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.

AI 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.

Live credentials and model assets are always opt-in. Local development should use deterministic fixtures or explicitly installed untracked model files.

The execution contract covers admission, status, history, events, progress, retries, cancellation, timers, waits, checkpoints, artifacts, concurrency keys, maintenance, and plugin discovery.

Vyral uses two canonical mutation shapes:

- synchronous operations return only after the requested effect is complete;
- receipt-bound asynchronous operations durably admit work and return a run or job receipt whose status can be queried independently.

The 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.

Vyral can also sit inside an existing orchestrator without replacing it. The
[Prefect receipt-flow example](/Univeracity/vyral/blob/main/examples#prefect-composition) lets
Prefect own schedules, task retries, and operator visibility while Vyral owns
durable admission, status, and results. It is a composition recipe, not a
Prefect adapter or qualification claim.

Start with the [execution design](/Univeracity/vyral/blob/main/design/execution-runtime.md),
[admission contract](/Univeracity/vyral/blob/main/design/admission-contract.md),
[plugin authoring guide](/Univeracity/vyral/blob/main/design/execution-runtime-plugin-authoring.md), and
[current limitations](/Univeracity/vyral/blob/main/docs/reference/execution-runtime-limitations.md).

| Area | Current posture |
|---|---|
| Local SQLite records, objects, retrieval, and execution | Reference path; deterministic conformance |
| PostgreSQL/pgvector and CanonicalStore | Implemented; live deployment evidence remains environment-specific |
| Azure Durable Functions execution | Live qualified; Azure storage adapters retain their separate preview posture |
| AWS storage and execution | Live qualified for isolated S3, DynamoDB, and SQS; managed OpenSearch remains subject to end-user validation |
| Google execution | Live qualified; other Google adapters retain their separate qualification posture |
| Temporal coordinator and projection | Prototype; disposable and operator-provisioned qualification gates |
| Cloudflare R2 | Preview object-store adapter |

An adapter is `live_qualified`

only when the versioned
[qualification matrix](/Univeracity/vyral/blob/main/qualification/README.md) records the required evidence.
The matrix is generated from the canonical JSON report; availability, a
successful build, or a package version alone does not establish that claim.
Adapter authors should begin with the
[adapter contributor guide](/Univeracity/vyral/blob/main/docs/contributing/adapter-contributor.md).

```
src/           .NET contracts, runtimes, server, and provider adapters
clients/       Python and JavaScript HTTP SDKs; Go external-worker client
runtimes/      Peer runtime implementations, currently Python
contracts/     OpenAPI-derived public SDK catalog and JSON schemas
conformance/   Language-neutral cross-runtime fixtures
examples/      Short HTTP client recipes
samples/       Runnable .NET and execution examples
tests/         Unit, integration, conformance, and adapter suites
qualification/ Versioned adapter qualification report and policy
design/        Contract and runtime designs
docs/          User, contributor, maintainer, and reference documentation
deploy/        Deployment preflights and qualification shapes
packaging/     Shared package landing-page inputs
scripts/       Local start, generation, verification, and release gates
```

The ordinary deterministic checks are:

```
scripts/run-dotnet-tests.sh Vyral.sln

npm ci --ignore-scripts --prefix clients/javascript
npm test --prefix clients/javascript

python3 -m pip install \
  --editable 'clients/python[typecheck]' \
  --editable 'runtimes/python[dev]'
python3 -m unittest discover -s clients/python/tests -p 'test_*.py'
scripts/verify-python-runtime.sh
```

Contract generation and repository-policy checks run in CI. Before treating a commit as releasable, run the larger artifact and consumer gate:

```
scripts/verify-release-artifacts.sh
```

Live provider gates are separate, explicit, and credential-bearing. They are
not part of the default local test suite. Release and publication procedures
are documented in the [release process](/Univeracity/vyral/blob/main/docs/maintainers/releasing.md).

| Topic | Document |
|---|---|
| Documentation index |
|

[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.
- The Python peer runtime remains a prototype until its remaining promotion evidence and independent review are complete.
- Provider behavior is limited to the portable contract; provider-native features may require application-owned extensions.
- Local deterministic embeddings validate mechanics, not semantic quality.
- Live provider qualification requires operator-owned infrastructure, least-privilege credentials, and explicit execution.
- CanonicalStore is intentionally narrower than a general relational database.
- MCP is opt-in, and write tools require an explicit allowlist.

Read [CONTRIBUTING.md](/Univeracity/vyral/blob/main/CONTRIBUTING.md), the
[code of conduct](/Univeracity/vyral/blob/main/CODE_OF_CONDUCT.md), and the relevant contract or adapter
design before proposing a change. Public behavior should be represented in
OpenAPI, the SDK catalog, conformance fixtures, and qualification evidence—not
only in one implementation.

Vyral is licensed under [Apache License 2.0](/Univeracity/vyral/blob/main/LICENSE). Third-party notices and
project trademark guidance are in [THIRD-PARTY-NOTICES.md](/Univeracity/vyral/blob/main/THIRD-PARTY-NOTICES.md)
and [TRADEMARKS.md](/Univeracity/vyral/blob/main/TRADEMARKS.md).

A [Univeracity](https://univeracity.com) project ·
[openvyral.com](https://openvyral.com)