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, an unannotated Python parameter) register a placeholder and resolve the schema later. Stages still reach them — attaching one performs the resolution — but until it happens there is no schema to validate CEL against, so a malformed expression is accepted at insert time and fails, or silently does nothing, at call time. Prefer static schemas; see How tests work for what that costs you.

​
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.
The service is the coordinator: the image is coordinator-server, its settings are COORDINATOR_*, the client endpoint override is VARIANZ_COORDINATOR_ENDPOINT, and the SDK entry points are initCoordinator (Node) and CoordinatorBinding (Java/Kotlin). “Registry” in these docs only ever means a package registry — PyPI, npm, Maven Central, pkgs.varianz.io. If a snippet you have uses registry/REGISTRY_ names, see Releases.