Terraform providers as first-class Nix values.
Describe real infrastructure as Nix instead of HCL. A thin Go executor drives unmodified Terraform and OpenTofu provider binaries, and what the cloud returns flows back into Nix, which re-evaluates until nothing is left unknown.
Status: early but real. The round trip works across providers, and AWS applies, updates, replaces and destroys today. Expect rough edges; the IR and the flake interface are the stable parts.
Website · Quick start · Docs · Registry · Discussions
Nivis is Latin for "of snow". Formerly nixform, then Terrae Nivis.
Coming from Nix? The missing half is the provider ecosystem. A provider is a
plugin binary that speaks to one cloud API, and Nivis runs any
OpenTofu-compatible provider as-is. A resource is an attrset built with
mkResource; compose it with the functions and modules you already write.
Coming from Terraform? The missing half is the language. Same providers, same
plan, apply and destroy, but a flake.nix takes the place of your .tf files,
and aws_s3_bucket.demo.id becomes bucket.refAttr "id": an ordinary value you
can pass to any function. Nix also builds machines, so a NixOS image and the
cloud resources that boot it can live in one expression.
| main.tf | flake.nix (excerpt) |
|---|---|
provider "aws" {
region = "eu-central-1"
}
resource "aws_s3_bucket" "demo" {
force_destroy = true
} |
providers.aws = lib.mkProvider {
source = "registry.opentofu.org/hashicorp/aws";
config.region = "eu-central-1";
};
resources = [
(lib.mkResource {
provider = "aws"; type = "aws_s3_bucket"; name = "demo";
config.force_destroy = true;
})
]; |
What Nix adds is the round trip: a value the cloud generates (an IP, an ID, a name) comes back into Nix, which re-evaluates to build the configuration that depends on it, phase by phase, until nothing is left unknown. The AWS tutorial shows it end to end.
You need Nix (with flakes). The first two steps touch no cloud account.
Run Nivis straight from the flake, no checkout:
nix run github:nivis-project/nivis#nivis -- --versionTake the guided tour. nivistutor scaffolds a tutorial project that runs
against in-repo fake providers, so you can watch a plan and an apply before any
credentials are involved:
nix shell github:nivis-project/nivis#nivis github:nivis-project/nivis#tutor
nivistutorThen point Nivis at a flake that describes your infra. A minimal one:
{
inputs.nivis.url = "github:nivis-project/nivis";
outputs = { self, nivis }:
let lib = nivis.lib; in {
# `nivis` evaluates this attribute by default.
nivis.plan = ledger: lib.toIR {
providers.aws = lib.mkProvider {
source = "registry.opentofu.org/hashicorp/aws";
config.region = "eu-central-1";
};
resources = [
(lib.mkResource {
provider = "aws"; type = "aws_s3_bucket"; name = "demo";
config.force_destroy = true;
})
];
inherit ledger;
};
};
}From that directory, creating real resources in your own AWS account:
nivis plan # show what will change (+ create ~ update -/+ replace = no change)
nivis apply # apply, resolving across phases to a fixpoint
nivis state show <resource-id>
nivis destroy(nivis shells out to nix to evaluate your config, and fetches and
checksum-verifies real providers from the OpenTofu registry on first use.)
- New here? The getting-started guide walks the
offline demo (in-repo fake providers, no cloud) and schema codegen (
nivis gen). - Real infra? The AWS S3 tutorial builds a bucket and a file whose contents Nix generates from the bucket's name (the round trip), from an empty directory.
- Installing
nivis(nix shell,nix profile): see docs/INSTALL.md. - Browse it all on the docs site.
Nix evaluates your configuration to a JSON IR. Values that aren't known until
apply-time are emitted as typed placeholders, a __ref (another resource's
output) or a __derived (a value Nix computed from an output). The executor
ingests the IR, drives the providers, gathers their apply-time outputs into a
ledger, then re-evaluates Nix with that ledger injected so placeholders
resolve; deeper chains take more phases, to a fixpoint. The full reasoning and
why this (not an Output<T> promise model) is the honest, Nix-shaped approach
is in docs/OVERVIEW.md and
docs/DESIGN.md.
nivis.lib is pure (builtins only, no nixpkgs, so it evaluates without the
binary cache):
mkResource { provider; type; name; config; }: a resource, with output references (refAttr) for wiring one resource into another.mkData { provider; type; name; config; }: a datasource (existing infra to read, not create); its outputs feed resources viarefAttr, read per phase. See docs/DATASOURCES.md.mkProvider { source; config; }: a provider, config (incl. nested blocks) in Nix; flows into the provider'sConfigure.str/derived: build values from provider outputs (the round trip).mkVars: declare typed config variables with defaults (required when no default), resolved from--var/--var-file/NIVIS_VAR_*(an explicit--varwins). Read them asvars.<name>in the plan.drv/drvFile: mark a Nix build output (a derivation) sonivis applyrealises it before use;drv dusesd.passthru.filePathwhen present,drvFile d "sub/path"names a file explicitly. (See the EC2 tutorial.)toIR: serialize to the IR;mkResources(count/for_each) andevalModules(module composition).
nivis gen --provider <binary> --out <dir> generates typed constructors from any
provider's schema, including nested blocks (with the right list-vs-single shape).
The generated constructor doubles as the per-provider argument reference.
Versioned interfaces, change the spec before the shape:
- The IR:
docs/IR-CONTRACT.md+docs/ir-schema.json(the normative JSON Schema). Both the NixtoIRproducer and the Go consumer validate against it. - The flake interface:
nivis.plan = ledger → IR, evaluated each phase with the outputs ledger injected.
The round trip is not unique to Nivis, and we say so. NixOps 4 feeds provider outputs back into Nix too, structural dependencies included. What is particular here is that the Terraform-provider coupling is the whole product: unmodified provider binaries, fetched and checksum-verified from the OpenTofu registry, so every provider works on day one.
The comparison sets Nivis next to Terranix, OpenTofu/Terraform, Pulumi, NixOps, CDK and CloudFormation, including where Nivis is still young.
Ask questions, share what you built or propose an idea in Discussions. Report a bug or a provider that misbehaves in Issues.
Nivis is built with the standard Go toolchain; the flake (nix build .#nivis,
nix run .#nivis) is the packaged path. From a checkout:
go build -o bin/nivis ./cmd/nivis # the CLI
go test ./... # Go unit + e2e (uses the in-repo fakes)
bash tests/run-nix-tests.sh # Nix property tests + IR conformance
bash tests/check-docs-ssot.sh # docs single-source-of-truthThe repo follows a spec-driven process guided by openspec/ (the per-change
specs). Releases: docs/RELEASING.md.
Nivis's own code is Apache-2.0 (LICENSE). See LICENSING.md for the
breakdown and NOTICE for attributions.
