Running the coordinator locally

The coordinator ships as a Docker image. Unlike the SDK packages on pkgs.varianz.io, the image is pulled from Google Artifact Registry and does need credentials — your team’s access is set up during onboarding (details).

Local development (in-memory, plaintext)

docker run --rm -p 50051:50051 \
  -e COORDINATOR_INSECURE_PLAINTEXT=true \
  us-docker.pkg.dev/varianz-dist/coordinator-slim/coordinator-server:v0.2.1

Listens on gRPC port 50051 (dual-stack). It logs LocalCoordinator listening on http://[::]:50051 (dual-stack) when ready.
State is in-memory — sessions, stages, and registrations reset on restart. That’s usually what you want for dev and CI.
COORDINATOR_INSECURE_PLAINTEXT=true (or the --insecure-plaintext flag) lets the server accept plaintext connections. The server is TLS-required by default and refuses to start without either TLS material or this flag.

Clients connecting to a plaintext coordinator need VARIANZ_INSECURE_ALLOW_PLAINTEXT=true in their environment — both sides must agree. Docker tags are v-prefixed (v0.2.1), unlike the package-manager versions (0.2.1).

Flags and environment

Flag	Env	Purpose
`--port`, `-p`	`COORDINATOR_PORT`	Listen port (default 50051; `--port 0` picks a free port)
`--insecure-plaintext`	`COORDINATOR_INSECURE_PLAINTEXT`	Accept plaintext connections
`--tls-cert` / `--tls-key` / `--tls-key-password`	`COORDINATOR_TLS_*`	Serve TLS from PEM material
`--tls-keystore` / `--tls-keystore-password`	`COORDINATOR_TLS_*`	Serve TLS from a PKCS#12 keystore
`--config`	`COORDINATOR_CONFIG`	TOML config file
`--postgres-url`	`COORDINATOR_PG_URL`	Durable backend: Postgres with a write-behind cache
`--uncached` (with `--postgres-url`)	`COORDINATOR_PG_UNCACHED`	Postgres-direct, no cache layer

Flags and environment variables override the config file.

TLS for shared environments

For anything beyond a laptop — a shared dev cluster, CI infrastructure others connect to — run the coordinator with TLS:

docker run --rm -p 50051:50051 \
  -v /path/to/certs:/certs:ro \
  us-docker.pkg.dev/varianz-dist/coordinator-slim/coordinator-server:v0.2.1 \
  --port 50051 --tls-cert /certs/server.pem --tls-key /certs/server-key.pem

Clients then need no plaintext override; if the CA isn’t in the platform trust store, point them at it with VARIANZ_TLS_CA (client TLS settings).

CI tips

Bind --port 0 and parse the logged port to avoid collisions between parallel jobs, or give each job its own container network.
Start the coordinator before the services under test: services register their VPoints at startup (fail-open with a ~5s timeout, so a late coordinator means lazily-degraded VPoints rather than crashes — but tests will then see zero subscribers).
Tests that only exercise behavior inside a single process don’t need a coordinator at all — see local stages.

Getting started

Core concepts

Guides

SDK reference

Testing

Reference

Running the coordinator locally

Local development (in-memory, plaintext)

Flags and environment

TLS for shared environments

CI tips

​Local development (in-memory, plaintext)

​Flags and environment

​TLS for shared environments

​CI tips

Local development (in-memory, plaintext)

Flags and environment

TLS for shared environments

CI tips