What is Turf?

[EronWright]

Turf is a drop-in replacement for Terraform with agentic superpowers — full support for Terraform HCL and the public module registry, driven by an AI agent over the Model Context Protocol (MCP).

The idea. Terraform's plan is a genuinely great safety guarantee: it tells you exactly what will change before anything does. What if you kept that plan — but replaced the monolithic graph walker that mechanically executes it with an LLM that reasons over it? That's Turf's thesis: the agent is the execution engine. The plan tells the agent what's possible; the agent decides what happens — with judgment, policy, and conversation in the loop between every step. It's a real replacement, not a fork: your Terraform knowledge transfers, the providers are OpenTofu's, and the artifacts (standard, Terraform-compatible plan JSON) stay interoperable.

Why reasoning in the engine matters. A planning-and-execution engine with judgment built in can avoid costly mistakes, take smart compensating actions when something fails, enforce policies inline, and drive genuinely complex stacks that need multiple planning rounds. And because the agent is an MCP client, it's extensible by construction — it can reach for other tools mid-rollout (policy scanners, notifications, approval gates) without Turf having to hard-code any of them.

How it's built — two pieces.

• turf-mcp-server (the engine): holds state, plans, runs OpenTofu providers, and exposes everything — tools, skills, prompts, read-only turf:// resources — over MCP (stdio or HTTP). It works with any MCP client: the Turf CLI, Claude Desktop, cagent, kagent in Kubernetes.
• turf CLI (optional wrapper): launches the engine as a subprocess and gives you a familiar surface — turf chat (interactive), turf up / turf destroy (codified).

Under the hood it wraps OpenTofu internals via a stable "shim" layer, so Turf can track upstream while keeping its own API boundary.

What you can do with it

• Ad-hoc, in natural language — "spin up a bucket and a random name for it," and the agent plans, orders, applies.
• Codified IaC — point it at your .tf and it reconciles: detects creates/updates/orphans, plans a batch, applies in dependency order (turf up / turf destroy).
• Registry modules — one module block becomes a whole database.
• Multi-round convergence — a Kubernetes cluster + its CRDs + workloads, described as one stack and converged across phases via deferrals. (OpenTofu can't do this today.)
• Policy & approval gates — approval is a real seam in the workflow, a natural place to sample the model, run OPA/Sentinel, or ask a human before anything executes.

Project status. Turf is an early alpha / pre-release — expect gaps and rough edges, but the foundations are solid: the phase/effect execution model, deferrals, and codified reconciliation all work end-to-end. Current: v0.1.0-alpha (macOS Homebrew: brew install turfbuild/tap/turf). Full details and licensing in the README.

Questions about how any of this works? Ask right here. 🌱