Skip to main content
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.3 (v0.2.3 for the Go module and Docker tags).

Python

To make the index permanent, put it in requirements.txt:
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 coordinator.

TypeScript

The Node.js SDK works from TypeScript or plain JavaScript. Point the @varianz scope at pkgs.varianz.io, then install normally:
@varianz/vitest@0.2.3 requires Vitest 4 (peerDependencies: vitest ^4.1.9). On a project still using Vitest 3 or older, the install fails outright with ERESOLVE unable to resolve dependency tree. Upgrade Vitest first; --legacy-peer-deps will install but is not supported.
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

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 does not work. It copies only directories containing Go source, so the bundled varianz/libs/<os>/<arch>/libvarianz_go_binding.a archives are dropped. The command succeeds silently and vendor/modules.txt looks correct; the failure appears at link time:
Copy the archives in after vendoring:
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:
glibc 2.38 or newer is required. The bundled native is built against it. On Debian 12 (“bookworm”, glibc 2.36) the link fails with undefined reference to '__isoc23_sscanf' — the __isoc23_* symbols are the giveaway. Use Debian 13 (“trixie”, glibc 2.41) or another distribution with glibc ≥ 2.38.At runtime the binary also needs libgcc_s.so.1. gcr.io/distroless/base does not ship it, so the image builds and then dies at start with error while loading shared libraries: libgcc_s.so.1. Use gcr.io/distroless/cc, or a -slim Debian image based on trixie.
Cross-compilation. Pure-Go services cross-compile for free with GOOS/GOARCH. With CGo enabled you need a full cross C toolchain for the target, so it is usually simpler to build natively for each target platform (a native runner per architecture, or emulation) than to set one up. Don’t force --platform=$BUILDPLATFORM in the builder stage — CGo must compile for the runtime platform. Summary of runtime images: gcr.io/distroless/cc-debian13 or debian:trixie-slim work. distroless/base (no libgcc_s.so.1), distroless/static and scratch (no libc), and anything bookworm-based (glibc too old) do not.
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. Use Gradle 9.0 or newer on JDK 24+. Gradle 8.x — including the final 8.14.5 — aborts during configuration with java.lang.IllegalArgumentException: 25.0.2 before the plugin is reached. Upgrade the wrapper from a JDK the old Gradle does support; the wrapper task is itself run by the broken Gradle.
Plugin options: 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.3-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), and requires Kotlin 2.3 or newer — on 2.1.x every build fails with NoSuchMethodError: SequencesKt.sequenceOf. See Kotlin SDK → Supported versions for the full matrix.
The pluginManagement repository block is the same as for Java, and so is the project-level repositories {} block — you need both. The extension’s options are listed on the Kotlin SDK page. Annotation attributes need named arguments in Kotlin: @VPoint(name = "…"), not positional.

Getting the coordinator image

The SDK packages above are anonymous. The coordinator image and the other non-package artifacts are not — they need a Varianz API key (var_live_…, from your Varianz contact): Everything is one host and one credential. No gcloud, no Google account, nothing to set up during onboarding — which is what makes this usable from CI. Pick the archive matching the machine that will run the coordinator, load it, and check the tag:
docker load prints the tag it created. It is the same name and digest the image carries in the container registry, so every docker run example in these docs works unchanged after loading.
Two things about the archives, both consequences of how Docker works rather than choices:They are per-architecture, and there is no multi-arch archive. docker load cannot consume a manifest list, so pick the line matching the runtime host. Note the package and the filename both change — …-linux-aarch64/…/coordinator-slim-image-arm64.tar.gz, not just the package — so editing one URL into the other gives a 404. Loading the wrong architecture succeeds and then fails to start with an exec-format error.Archives are versioned like the packages, not like the image: 0.2.3 in the URL, while the loaded image tag is v0.2.3.
Running it is covered in Running the coordinator locally.

Downloading generic artifacts with an API key

Native libraries and an offline copy of these docs, versioned with the release, are served the same way — same host, same API key:
The key is read from headers only — Authorization: Bearer <key> or x-api-key: <key>. A key passed in the query string is ignored and the request fails as unauthenticated, deliberately: credentials in URLs end up in proxy and CI logs. Keys are scoped, expiring, and revocable server-side; treat one like a password and have it revoked if it leaks.

After installing

Every SDK is disabled by default — set VARIANZ_ENABLED=true and point it at a coordinator to activate it. (Java/Kotlin additionally need the varianz-agent attached, which the build plugins handle for test and run tasks.) A local plaintext coordinator additionally needs 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.