Configuration

Enabling the SDK

Varianz is opt-in: the SDK is disabled by default. A service that carries the SDK but is given no configuration stays dormant — VPoints pass through, nothing registers, no native library is touched, and every SDK call succeeds as a no-op. Resolution order (first match wins):

VARIANZ_ENABLED environment variable — wins unconditionally when set.
enabled key in a config file — VARIANZ_SDK_CONFIG=<path> if set, else ./varianz.toml, else ~/.varianz/sdk.toml. First existing file wins; files are not merged.
Built-in default: disabled.

Accepted boolean tokens (case-insensitive): true = true, 1, on, yes, enabled; false = false, 0, off, no, disabled. An unparseable value or unreadable config resolves to disabled with a single warning — the same fail-open posture as the rest of Varianz: when anything is wrong, VPoints simply run your original code. The config file schema is a single top-level key; unknown keys are ignored:

# varianz.toml
enabled = true

The state is resolved once at SDK initialization and cached for the process lifetime — there is no hot reload. The SDK logs exactly one startup line stating its state and source, e.g.:

[varianz] ENABLED (source: env:VARIANZ_ENABLED)
[varianz] DISABLED (source: default; set VARIANZ_ENABLED=true to activate)

The toggle behaves identically in every SDK. For Java/Kotlin, interception additionally requires the varianz-agent to be attached (Gradle weave, Maven -Dvarianz.skipAgent=true) — see Java SDK.

Coordinator endpoint

VARIANZ_COORDINATOR_ENDPOINT is the canonical name. Prefer it everywhere — application side and test side, every language.

Application side

The endpoint is normally passed in code — Varianz("http://..."), initCoordinator({ endpoint }), varianz.WithEndpoint(...), CoordinatorBinding.init(...). It is a default, not an instruction: the environment outranks it, because whoever deploys a build must be able to repoint it without rebuilding it. Precedence, highest first:

VARIANZ_COORDINATOR_ENDPOINT — outranks everything, including an endpoint passed at the call site.
endpoint in a config file named by VARIANZ_SDK_CONFIG — naming a file is a deployment act, so it also outranks the call site.
The endpoint passed at the call site.
endpoint in a config file found by search (./varianz.toml, ~/.varianz/sdk.toml).

An empty or whitespace-only variable counts as unset. When two tiers disagree the SDK logs the override rather than applying it silently:

[varianz] config 'VARIANZ_COORDINATOR_ENDPOINT': value from call site ("http://localhost:50351")
          is overridden by environment variable ("http://coordinator.internal:50051")
[varianz] coordinator endpoint http://coordinator.internal:50051 (source: env:VARIANZ_COORDINATOR_ENDPOINT)

If no tier supplies an endpoint, Python, Go and the JVM run local-only — VPoints work, local stages apply, nothing is fetched or published. Node’s initCoordinator() is the exception: it raises

no coordinator endpoint: set VARIANZ_COORDINATOR_ENDPOINT, point VARIANZ_SDK_CONFIG at a config file, add 'endpoint' to a config file, or supply one at the call site

. (A Node service that never calls initCoordinator at all is local-only, like the others.)

A stale VARIANZ_COORDINATOR_ENDPOINT silently wins. Inherited from a base image, a shared Compose file or a sibling service, it overrides the endpoint in your code and every stage goes inert. Unset it unless you intend it to be authoritative, and check the (source: …) startup line. Go exposes the resolved value directly:

if ep, ok := varianz.ResolvedEndpoint(); ok && ep != wanted {
    log.Fatalf("varianz: environment overrides the configured endpoint (%s != %s)", ep, wanted)
}

Python has varianz.resolved_endpoint(), Node resolvedEndpoint() from @varianz/client, and the JVM VarianzCoordinatorClient.resolvedEndpoint(). All four report what the SDK resolved, and null/false when nothing supplied one — distinct from an empty endpoint, which is what selects local-only mode.

Test side

Test fixtures resolve the endpoint so a suite can move between a laptop and CI without edits. Every one of them puts an explicitly supplied endpoint first — the reverse of the application side, because naming a coordinator in a test is a deliberate act by whoever ran it.

Framework	Resolution order
pytest	`--varianz-endpoint` → `VARIANZ_COORDINATOR_ENDPOINT` → `VARIANZ_COORDINATOR_ADDR` (deprecated) → `varianz.toml` → `http://localhost:50051`
Vitest / Playwright	fixture `endpoint` option → `VARIANZ_COORDINATOR_ENDPOINT` → `VARIANZ_TEST_ENDPOINT` → `VARIANZ_COORDINATOR_ADDR` → `VARIANZ_ENDPOINT` (all three deprecated) → `varianz.toml` → `http://127.0.0.1:50051` (Playwright: `http://127.0.0.1:18051`)
JUnit 5 / Kotest	`@VarianzTest(endpoint = …)` / `VarianzExtension(endpoint = …)` → `-Dvarianz.endpoint` → `VARIANZ_COORDINATOR_ENDPOINT` → `varianz.toml` → `http://127.0.0.1:50051`
Go	the `endpoint` argument to `vt.NewSession(t, endpoint)`

Deprecated spellings

Variable	Still read by	Status
`VARIANZ_COORDINATOR_ENDPOINT`	every runtime, application and test side	Canonical. Use this
`VARIANZ_COORDINATOR_ADDR`	pytest plugin; `@varianz/client` (Vitest, Playwright)	Deprecated, removed before 1.0. One-time warning. Not read by any application SDK, and not read by the JVM at all
`VARIANZ_ENDPOINT`	`@varianz/client` only	Deprecated, removed before 1.0. One-time warning. Not read by the JVM
`VARIANZ_TEST_ENDPOINT`	`@varianz/client` only	Deprecated, removed before 1.0. One-time warning

A deprecated spelling is consulted only when VARIANZ_COORDINATOR_ENDPOINT is unset. Go, the JVM and C++ accept no alias at all; Node and Python keep shims because both ship through package registries, where a pinned install and a CI config keep exporting an old name long after an upgrade.

On the JVM a wrong variable name is a green test that tested nothing. With no alias and no warning, a suite exporting anything other than VARIANZ_COORDINATOR_ENDPOINT falls back to http://127.0.0.1:50051: insert() returns an id, awaitSyncOrFail() passes, and every stage silently no-ops. The only symptom is awaitSync reporting 0/0 and a [varianz] WARNING: No subscribers received the … staged instruction(s) line on stderr — so assert on confirmedClients() in CI. If you are upgrading a suite, see Releases.

TLS

SDK clients always verify TLS against the platform trust store by default. There is no code-side override for plaintext — only the environment:

Variable	Behavior
`VARIANZ_INSECURE_ALLOW_PLAINTEXT`	`true` permits a plaintext (`http://`) endpoint — required for the local dev coordinator. It permits, never forces: an `https://` endpoint always dials TLS. Setting it to `false` explicitly re-enables TLS enforcement even where a harness defaulted to plaintext
`VARIANZ_TLS_TRUST`	Trust mode: `system` (default), `jdk`, or `file`
`VARIANZ_TLS_CA`	Path to a CA bundle (PEM) or truststore
`VARIANZ_TLS_CA_PASSWORD`	Password for the truststore, if any
`VARIANZ_TLS_SERVER_NAME`	Override the SNI / certificate hostname

Every SDK client (Python, TypeScript, Go, JVM) reads these identically. Rotating a CA file on disk doesn’t affect established connections — reconnect or restart the client.

Environment tags

Stages can be scoped to deployment environments. Clients advertise theirs via SDK options (for example initCoordinator({ region, cluster, tags })) or environment variables:

Variable	Field
`VARIANZ_APPLICATION_NAME`	Application name
`VARIANZ_REGION`	Region
`VARIANZ_CLUSTER`	Cluster

Git provenance

VPoints record their code location (file, line, git commit) for tooling. Detection reads the local .git; production artifacts usually run without one, so set these in your build/deploy pipeline:

Variable	Content
`VARIANZ_REPO_URL`	Repository URL
`VARIANZ_GIT_BRANCH`	Branch
`VARIANZ_GIT_COMMIT`	Commit SHA
`VARIANZ_GIT_DIRTY`	`1`/`0` — working tree dirty flag

Values merge field-by-field on top of whatever was auto-detected.

Build-time switches

Variable	Effect
`VARIANZ_SKIP_CODEGEN`	Build-integration tools emit no generated code. Independent of `VARIANZ_ENABLED` — the tools resolve full schemas either way, so a build machine needs no Varianz environment
`VARIANZ_DISABLE_AUTO_LOAD`	Node only, exact value `1`: skip auto-loading the scanner manifest from `node_modules/.varianz/`

JVM equivalent for the processor: -Avarianz.proc.enabled=false.

The standard local-dev environment

For the common case — local plaintext coordinator on 50051 — every service and test process needs:

export VARIANZ_ENABLED=true
export VARIANZ_INSECURE_ALLOW_PLAINTEXT=true   # plaintext coordinator only

Getting started

Core concepts

Guides

SDK reference

Testing

Reference

Enabling the SDK

Coordinator endpoint

Application side

Test side

Deprecated spellings

TLS

Environment tags

Git provenance

Build-time switches

The standard local-dev environment

​Enabling the SDK

​Coordinator endpoint

​Application side

​Test side

​Deprecated spellings

​TLS

​Environment tags

​Git provenance

​Build-time switches

​The standard local-dev environment

Enabling the SDK

Coordinator endpoint

Application side

Test side

Deprecated spellings

TLS

Environment tags

Git provenance

Build-time switches

The standard local-dev environment