Skip to main content
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. 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.

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

​
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:
Full syntax and matching rules: 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.
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.