> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varianz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# The registry

> The Varianz registry is the coordination service that holds VPoint schemas, routes stages to subscribed services, and streams samples back to tests.

The **registry** is the service everything else connects to. Instrumented services register their VPoints with it and subscribe for stage updates; tests connect to it to create sessions, insert stages, and receive samples. It listens on gRPC port **50051**.

```mermaid theme={null}
flowchart LR
    service["Service<br/>(app SDK)"]
    registry["Registry<br/>:50051"]
    test["Test<br/>(test SDK)"]

    service -- "register VPoints,<br/>subscribe to stages" --> registry
    registry -- "stages delivered" --> service
    test -- "insert stages,<br/>create sessions" --> registry
    registry -- "samples streamed" --> test
```

For local development you run it in-memory in Docker (state resets on restart); it can also run against Postgres for durability. See [Running the registry locally](/reference/local-registry).

## What it holds

* **The VPoint catalog** — every registered VPoint's name and schema (its *VPD*, variation point descriptor). This is what CEL validation checks stages against, and what the [MCP tools](/guides/ai-assisted-testing) query.
* **Sessions and their stages** — which expressions are attached to which VPoints, in which session, with which routing filters.
* **Live subscriptions** — which service instances are connected and which VPoints each one registered.

## Registration: eager vs. lazy

When a service starts, VPoints with statically-derivable schemas register immediately — stages work from the very first request. If the registry is unreachable, registration times out (about 5 seconds) and the service proceeds anyway: Varianz **fails open**, and VPoints degrade to pass-throughs rather than blocking your service.

VPoints whose schema can't be derived statically (for example, unannotated Python functions) register **lazily** on their first call. Until that call happens, the VPoint doesn't exist in the registry, so tests can't validate CEL against it or attach stages to it. Prefer static schemas; where you can't, trigger the VPoint once before inserting stages — see [How tests work](/testing/overview#lazy-vpoints).

## Stage routing

A stage names a **target** — usually a VPoint name suffix like `payment/charge` — and the registry matches it against registered VPoints on `/` boundaries. Exactly one match is required; ambiguity is an error. Targets can also be scoped by application name, region, cluster, and tags, so a stage reaches only the instances you mean:

```
checkout-service:payment/charge region=us-east-1 cluster=prod
```

Full syntax and matching rules: [Naming and routing](/reference/naming-and-routing).

## Delivery confirmation

Insertion and delivery are separate steps. Test SDKs expose `await_sync_or_fail` — a barrier that waits until every currently-connected subscriber whose VPoints match your stages confirms receipt, and surfaces validation problems found along the way. It confirms subscribers *connected at that moment*; it does not predict services that connect later. The practical implications for tests are covered in [How tests work](/testing/overview).