Installation

All Varianz packages are served from pkgs.varianz.io. It proxies only the varianz packages — your other dependencies keep resolving from PyPI, npm, or Maven Central as usual, and no credentials are required. All ecosystems share the release version: 0.2.1 (v0.2.1 for the Go module and Docker tags).

Python

pip install "varianz==0.2.1" "varianz-pytest==0.2.1" \
  --extra-index-url https://pkgs.varianz.io/python/simple/

To make the index permanent, put it in requirements.txt:

--extra-index-url https://pkgs.varianz.io/python/simple/
varianz==0.2.1
varianz-pytest==0.2.1

Packages: varianz (runtime, includes the varianz-scan CLI) and varianz-pytest (pytest plugin — install only where you run tests).

Use --extra-index-url, not --index-url. --index-url replaces PyPI, so every other dependency in the same command stops resolving. Keep the version pinned: placeholder packages named varianz and varianz-pytest exist on public PyPI (they hold the names and contain no SDK), and a pin guarantees you get the real package.

Platforms: wheels only (no sdist) for CPython 3.10–3.15 and PyPy 3.11 on macOS (x86_64, arm64) and Linux glibc/musl (x86_64, aarch64). Unsupported platforms fail with “no matching distribution found” rather than attempting a source build. Docker: wheels are platform-specific, so install inside the image (the Linux wheel) rather than copying a macOS install in. Alternatively, run tests from the host against the service in Docker — the service and the test process only need to reach the same registry.

TypeScript

The Node.js SDK works from TypeScript or plain JavaScript. Point the @varianz scope at pkgs.varianz.io, then install normally:

echo '@varianz:registry=https://pkgs.varianz.io/npm/' >> .npmrc

# Runtime (pulls @varianz/cel and @varianz/client with it)
npm install --save @varianz/node@0.2.1

# Test integrations — install whichever you use
npm install --save-dev \
  @varianz/vitest@0.2.1 \
  @varianz/playwright@0.2.1 \
  @varianz/scanner@0.2.1

Scope the registry; do not use --registry. The --registry flag redirects every lookup, so npm asks pkgs.varianz.io for public transitive dependencies and gets a 404. The @varianz:registry= line sends only @varianz/* there.

The matching native binary for your OS/CPU/libc is included in each tarball — no build tools, no postinstall step. Platforms: Node.js 22+ on macOS (arm64, x64) and Linux glibc/musl (x64, arm64). The using-based automatic stage cleanup requires Node 23+. TypeScript config: the decorator API uses TC39 (stage-3) decorators — TypeScript ≥ 5.0 with experimentalDecorators left at its default (false).

Go

go get go.varianz.io/sdk@v0.2.1

The module resolves like any other Go dependency. Native libraries are pre-built and bundled inside the module; platform-specific #cgo directives link the correct one automatically. go mod vendor works normally. CGo is required. The SDK links a Rust native library, so build with CGO_ENABLED=1. In Docker, that rules out the common CGO_ENABLED=0 + distroless/static pattern:

# Builder: needs gcc + glibc headers for CGo
FROM golang:1.22-bookworm AS builder
ENV CGO_ENABLED=1
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o /service ./cmd/service

# Runtime: needs glibc, not build tools
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /service /service
ENTRYPOINT ["/service"]

The runtime image can be debian:bookworm-slim or gcr.io/distroless/base-debian12; distroless/static and scratch will not work. Don’t force --platform=$BUILDPLATFORM in the builder stage — CGo must compile for the runtime platform.

If checksum verification fails for this module in your environment (for example, behind a proxy that blocks proxy.golang.org), set GONOSUMDB='go.varianz.io/*' or use GOPRIVATE=go.varianz.io/*.

Java

The Gradle plugin adds the SDK modules, configures the annotation processor, and attaches the varianz-agent to Test and JavaExec tasks automatically.

// settings.gradle.kts
pluginManagement {
    repositories {
        maven { url = uri("https://pkgs.varianz.io/maven") }
        gradlePluginPortal()
    }
}

// build.gradle.kts
plugins {
    id("io.varianz.sdk") version "0.2.1"
}

repositories {
    mavenCentral()   // keep it — processor deps (JavaParser, ByteBuddy) resolve here
    maven { url = uri("https://pkgs.varianz.io/maven") }
}

varianz {
    sdkVersion.set("0.2.1")
}

Plugin options:

Property	Default	Description
`sdkVersion`	—	SDK version resolved from your repositories. Mutually exclusive with `sdkDir`; exactly one must be set
`sdkDir`	—	A local directory of SDK JARs instead of a repository (air-gapped builds)
`includeJunit`	`true`	Add `io.varianz:varianz-junit` to `testImplementation`
`weave`	`true`	Attach the `varianz-agent` to `Test`/`JavaExec` tasks. `false` = `@VPoint` methods run uninstrumented
`failOnWarning`	`false`	Treat annotation-processor warnings as errors

If your project uses protobuf/gRPC, also add those to annotationProcessor so the processor can resolve proto types in @VPoint signatures.

Production launchers need the agent too. The plugin attaches -javaagent: only to Gradle Test and JavaExec tasks. A deployed service started from an installDist script or java -jar runs without the agent — @VPoint methods execute their original bodies and stages never fire. Add -javaagent:varianz-agent-0.2.1-agent.jar (and, on Java 22+, --enable-native-access=io.varianz.native_loader) to the production launch command. See Java SDK for details.

Maven users: see the Java SDK page for the full pom.xml setup (BOM import, varianz-starter, java-processor with the all classifier, and the varianz-maven-plugin prepare-agent goal). Docker: both glibc images (eclipse-temurin:21-jdk) and Alpine (eclipse-temurin:21-jdk-alpine) work — the JARs bundle glibc and musl native libraries.

Kotlin

Kotlin uses its own KSP-based plugin, io.varianz.sdk.kotlin (not the Java plugin). Four things trip up first-time setup:

plugins {
    id("com.google.devtools.ksp") version "2.1.10-1.0.29" // 1. KSP must come first
    id("io.varianz.sdk.kotlin")                           // 2. Kotlin-specific plugin id
}

dependencies {
    ksp("com.github.javaparser:javaparser-core:3.27.0")   // 3. plugin does not add this
}

// 4. Configure via the typed extension
configure<io.varianz.gradle.kotlin.VarianzKotlinExtension> {
    sdkVersion.set("0.2.1")
}

The pluginManagement repository block is the same as for Java. Annotation attributes need named arguments in Kotlin: @VPoint(name = "…"), not positional.

After installing

Every SDK is disabled by default — set VARIANZ_ENABLED=true and point it at a registry to activate it. (Java/Kotlin additionally need the varianz-agent attached, which the build plugins handle for test and run tasks.) Local plaintext registries additionally need VARIANZ_INSECURE_ALLOW_PLAINTEXT=true on every connecting process. See Configuration for the full environment-variable reference, and the Quickstart to verify your install end to end.

Getting started

Core concepts

Guides

SDK reference

Testing

Reference

Python

TypeScript

Go

Java

Kotlin

After installing

​Python

​TypeScript

​Go

​Java

​Kotlin

​After installing

Python

TypeScript

Go

Java

Kotlin

After installing