Introduction

Stategraph is a state management and visualization system for Terraform and OpenTofu. It replaces the flat state file (and the whole-state lock that comes with it) with a dependency graph of your infrastructure, stored on a server you can query, lock at the resource level, and reason about.

You keep writing normal Terraform. Stategraph changes where your state lives and what you can do with it.

Why Stategraph

A typical Terraform setup keeps state as a single blob in S3. That has two costs:

  • One lock per state. Any apply locks the entire state, so your team's changes serialize — even when they touch completely unrelated resources.
  • No visibility. The state is an opaque JSON file. There is no good way to ask "what depends on this?", "what would this change affect?", or "what is this costing me?".

Stategraph models state as a graph of resources and their dependencies. That single change unlocks the rest:

  • Velocity — parallel plan and apply with resource-level locking. Changes that touch disjoint resources run concurrently instead of waiting on each other. It's a drop-in for terraform plan / terraform apply.
  • Insights — blast-radius analysis, a dependency graph explorer, search, and a transaction timeline.
  • Inventory — query your whole estate with SQL, and find cloud resources Terraform isn't managing yet (gap analysis).
  • Cost Analysis — per-state and per-tenant cost, attribution, and a cost delta at plan time.

How it works

You run two things: the CLI (local) and the Server (a coordinator backed by PostgreSQL).

  1. You run stategraph tf plan or stategraph tf apply from the CLI.
  2. The CLI sends your configuration and the requested change to the Server.
  3. The Server records the change as a transaction and returns the minimal, self-contained bundle of configuration the change needs.
  4. The CLI runs Terraform/OpenTofu locally against your cloud with your own credentials, then reports the outcome back.
  5. The CLI shows you the result.

The important part: your authoritative state lives on the Server, but your cloud credentials never leave the machine running the CLI. The Server never runs Terraform and never sees your cloud. See Architecture for the full picture.

Where to start

  • New to the model? Read Core concepts — the vocabulary you'll see everywhere.
  • Want to get hands-on? Follow the Quickstart — install, connect, import a state, and explore in about ten minutes.

Stategraph runs as a hosted service we manage, or self-hosted in your own environment where your state and data never leave it.