> ## 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 coordinator

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

The **coordinator** 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)"]
    coordinator["Coordinator<br/>:50051"]
    test["Test<br/>(test SDK)"]

    service -- "register VPoints,<br/>subscribe to stages" --> coordinator
    coordinator -- "stages delivered" --> service
    test -- "insert stages,<br/>create sessions" --> coordinator
    coordinator -- "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 coordinator locally](/reference/local-coordinator).

## 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 coordinator 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 coordinator's catalog, 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 coordinator 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).

<Note>
  Earlier pre-release material called this service the *registry*. In 0.2.1 the name is **coordinator** throughout: the image is `coordinator-server`, its settings are `COORDINATOR_*`, the client endpoint override is `VARIANZ_COORDINATOR_ADDR`, and the SDK entry points are `initCoordinator` (Node) and `CoordinatorBinding` (Java/Kotlin). If a snippet you have uses `registry`/`REGISTRY_` names, it predates this release. "Registry" in these docs now only ever means a *package* registry — PyPI, npm, Maven Central, `pkgs.varianz.io`.
</Note>