IaC Studio Documentation

What IaC Studio Does

Design visually

Drag resources onto a canvas, connect dependencies, edit properties, and preview generated code as the topology changes.

Import real projects

Browse local folders, inspect Terraform, OpenTofu, Ansible, Pulumi, and layered projects, then rebuild the visual graph from disk.

Use AI without giving up control

Run with local Ollama models or API-backed providers. AI can create topologies, explain failures, suggest next resources, and fix plan errors.

Validate before apply

Policy checks, security scans, drift detection, plan gates, command timeouts, and kill controls keep risky operations explicit.

Round-trip code

Canvas edits write IaC files, file changes resync the graph, and the Monaco editor supports Terraform, OpenTofu, Ansible, Pulumi, YAML, and JSON.

Package and promote modules

Inspect module usage, search registry metadata, and promote selected resources into reusable Terraform module structure.

Quick Start

The fastest path is the interactive setup script. It checks dependencies, asks how you want AI configured, builds the app from source, and starts the local server.

./scripts/setup.sh

What the setup script does: ./scripts/setup.sh does not download the release binaries. It checks your platform, installs missing dependencies when you approve, configures optional AI, builds bin/iac-studio locally, and can start that freshly built local server for you.

What the install script does: scripts/install.sh downloads the latest matching release binary from GitHub, verifies it with checksums.txt when available, installs it as iac-studio, and leaves source builds out of the path.

Manual local install

Use this path when you want predictable commands for a development machine.

git clone https://github.com/olandodeflexy/IaCStudio.git
cd IaCStudio
make deps
make build
./bin/iac-studio

Open http://localhost:3000.

Download a release binary

Release assets are local server binaries. They are useful when you want to run IaC Studio without Docker and without building from source. Download the file that matches your operating system and CPU, make it executable on macOS or Linux, run it, then open http://localhost:3000.

Machine	Release asset	How to run
Apple Silicon Mac	`iac-studio-darwin-arm64`	`chmod +x ./iac-studio-darwin-arm64 && ./iac-studio-darwin-arm64`
Intel Mac	`iac-studio-darwin-amd64`	`chmod +x ./iac-studio-darwin-amd64 && ./iac-studio-darwin-amd64`
Linux x86_64	`iac-studio-linux-amd64`	`chmod +x ./iac-studio-linux-amd64 && ./iac-studio-linux-amd64`
Linux ARM64	`iac-studio-linux-arm64`	`chmod +x ./iac-studio-linux-arm64 && ./iac-studio-linux-arm64`
Windows x64	`iac-studio-windows-amd64.exe`	`.\iac-studio-windows-amd64.exe`
Windows ARM64	`iac-studio-windows-arm64.exe`	`.\iac-studio-windows-arm64.exe`

# Optional: rename the downloaded macOS or Linux asset first
mv iac-studio-darwin-arm64 iac-studio
chmod +x ./iac-studio
./iac-studio --projects-dir "$HOME/iac-projects"

On macOS, unsigned release binaries may be quarantined by Gatekeeper after download. If the binary is blocked, remove the quarantine attribute and run it again.

xattr -d com.apple.quarantine ./iac-studio
./iac-studio

checksums.txt is for verifying download integrity. It is not an executable and does not start the app.

Install the latest release with a script

Use this when you want the release binary path but do not want to manually pick the asset. The installer detects your OS and CPU, downloads the matching asset, verifies the checksum, and installs iac-studio.

curl -fsSL https://raw.githubusercontent.com/olandodeflexy/IaCStudio/main/scripts/install.sh | bash
iac-studio

Run with Docker

The container includes the server, built web UI, Terraform, and OpenTofu.

docker run --rm -it \
  -p 3000:3000 \
  -v "$HOME/iac-projects:/projects" \
  ghcr.io/olandodeflexy/iacstudio:latest

Default server behavior: the binary binds to 127.0.0.1:3000, stores projects in ~/iac-projects, and expects Ollama at http://localhost:11434 unless you override flags or AI settings.

First 10 Minutes

Start IaC Studio. Run ./bin/iac-studio or the Docker command, then open the browser.
Create or import a project. Start from an empty project, describe a topology, upload a diagram, or browse to an existing folder.
Pick the tool and provider. Choose Terraform, OpenTofu, Ansible, Pulumi, or a layered multi-environment layout.
Add resources. Use the left resource palette, AI chat, or topology builder. Connect nodes to encode dependencies.
Review generated code. Open the Code tab, inspect files, and save edits back to disk.
Validate. Run policy checks and security scans before running infrastructure commands.
Run safely. Use Init, Plan, then Apply. Apply requires a successful plan and explicit confirmation.

Interface Tour

Area	Purpose	Common actions
Project Launcher	Start, import, or restore projects.	Create from scratch, build from text, upload diagram, open recent projects.
App Header	Global controls for tool, provider, environment, and command execution.	Run init/plan/apply, open AI settings, reveal project folder, switch environment.
Workspace Sidebar	Resource catalog, generated file list, next-step suggestions, and starter guide.	Search resources, add nodes, inspect generated files, use suggestions.
Canvas	Visual topology editing.	Drag nodes, connect resources, switch between freeform and swimlane layouts.
Inspector	Edit selected node and edge details.	Change names, properties, references, tags, and connection metadata.
Code Editor	Live generated files and manual code edits.	Edit Terraform, OpenTofu, Pulumi TypeScript, YAML, JSON, and generated diffs.
Policy Studio	Run built-in and engine-backed policy checks.	Review violations, acknowledge allowed exceptions, block unsafe apply attempts.
Scan Panel	Security scanner controls and findings.	Run scanners, map findings to compliance frameworks, generate CI workflow snippets.
Module Registry	Reusable module discovery and promotion.	Search modules, inspect versions, promote canvas resources to a module.
Terminal	Command logs and live process output.	Read plan/apply output, kill running commands, send failures to AI fix.
Chat Panel	AI assistant grounded in the selected tool and current project.	Generate resources, explain files, fix plan output, ask for suggestions.

Core Workflows

Create infrastructure from the canvas

Choose a provider, search the resource catalog, add nodes, then connect resources. Connections are not decorative: for Terraform and OpenTofu they become real references where the generator can infer safe relationships.

Import an existing project

Use the Import Wizard to browse local folders. IaC Studio scans supported files, detects the tool, parses resources, restores known coordinates, and writes a .iac-studio.json state file next to the project.

Build from a text topology

Describe the target architecture in natural language. The AI topology endpoint returns resources and edges, then the UI turns them into editable canvas objects and generated code.

Build from an image

Drop one or more architecture diagrams into the Vision import flow. The backend sends the image payloads to the configured AI provider, converts the result into a topology, and keeps the generated project editable.

Round-trip Pulumi and layered projects

Pulumi TypeScript resources are parsed from index.ts files, while layered projects use environment-aware folders such as environments/dev and shared module paths. The environment selector limits the canvas and code view to the active layer.

Run policy and security checks

Run policy engines and scanners before executing infrastructure commands. Blocking findings stop apply unless the API receives an explicit acknowledgement for the current request.

Detect drift and export

Drift detection compares state against code when Terraform state is present. Export converts the current topology into alternate formats such as Pulumi TypeScript, CDK Python, and CloudFormation where supported.

AI Setup

AI is optional. The app still works as a visual editor and runner without an AI provider. When enabled, AI requests are used for chat, topology generation, image topology import, plan fixes, suggestions, and agent workflows.

Local Ollama

ollama pull qwen2.5-coder:7b
./bin/iac-studio --ai-endpoint http://localhost:11434 --ai-model qwen2.5-coder:7b

OpenAI-compatible providers

OPENAI_API_KEY=sk-... \
OPENAI_MODEL=gpt-4o-mini \
./bin/iac-studio

Anthropic

ANTHROPIC_API_KEY=sk-ant-... \
ANTHROPIC_MODEL=claude-opus-4-7 \
./bin/iac-studio

Setting	Default	Use
`--ai-endpoint`	`http://localhost:11434`	Ollama or OpenAI-compatible base endpoint.
`--ai-model`	`deepseek-coder:6.7b`	Default model name used by the server.
`OPENAI_API_KEY`	unset	Enables OpenAI-compatible API calls.
`OPENAI_ENDPOINT`	`https://api.openai.com/v1`	Overrides the OpenAI-compatible API endpoint.
`OPENAI_MODEL`	`gpt-4o-mini`	Overrides the OpenAI model.
`ANTHROPIC_API_KEY`	unset	Enables Anthropic-backed requests.
`ANTHROPIC_MODEL`	`claude-opus-4-7`	Overrides the Anthropic model.

Privacy model: local Ollama requests stay on your machine. API providers receive the prompt content needed for the requested action. IaC Studio does not add telemetry or account tracking.

Policy, Security, and Runtime Safety

Local binding

The default server binds to 127.0.0.1. Docker uses 0.0.0.0 inside the container so the host port can map correctly.

Origin checks

CORS and WebSocket origin validation are intended to accept localhost development and app origins only.

Path sandboxing

Project names and file paths are normalized and validated to prevent traversal outside the configured projects directory.

Plan-before-apply

Apply is gated by a successful plan and can be blocked by policy findings unless explicitly acknowledged.

Command control

Infrastructure commands run through a safe runner with timeouts, captured logs, and a kill path.

Scanner output

Findings include severity, policy IDs, affected resources, compliance mapping, and remediation text where available.

API Reference

The browser talks to the Go backend over JSON REST endpoints and a WebSocket stream. Endpoints are rooted at the same host as the web app.

Area	Endpoints	Notes
Health and catalog	`GET /api/health` `GET /api/tools` `GET /api/catalog`	Detect installed tools and load provider resource catalogs.
Projects	`GET /api/projects` `POST /api/projects` `DELETE /api/projects/{name}`	Create, list, and delete local project folders.
State and resources	`GET /api/projects/{name}/resources` `POST /api/projects/{name}/sync` `GET /api/projects/{name}/state`	Parse IaC files, save generated files, and restore canvas metadata.
Commands	`POST /api/projects/{name}/run` `POST /api/projects/{name}/kill`	Run init, plan, apply, and stop active processes.
Import	`GET /api/browse` `POST /api/import`	Browse local directories and import existing projects.
AI	`POST /api/ai/chat` `POST /api/ai/chat/stream` `POST /api/ai/topology` `POST /api/ai/topology/image` `POST /api/ai/fix` `POST /api/ai/suggest` `POST /api/ai/settings`	Chat, streaming responses, topology generation, image import, plan fixes, suggestions, and provider settings.
Policy and scanning	`GET /api/policy/engines` `POST /api/projects/{name}/policy/run` `GET /api/security/scanners` `POST /api/projects/{name}/security/scanners/run` `GET /api/projects/{name}/security`	Run policy engines and security scanners against the current project.
Modules, drift, export	`GET /api/projects/{name}/modules` `GET /api/registry/modules/search` `POST /api/projects/{name}/promote-to-module` `GET /api/projects/{name}/drift` `GET /api/export/formats` `POST /api/export`	Discover modules, promote resources, detect drift, and export alternate IaC formats.
Realtime	`GET /ws`	Streams file changes, command output, process status, and UI refresh events.

Architecture

Browser UI
  React, Vite, Monaco, canvas panels
        |
        | REST + WebSocket
        v
Go server
  API router
  HCL, YAML, Pulumi parsers
  Code generators and exporters
  AI bridge
  Policy, scan, drift, module services
  Safe command runner
        |
        v
Local project directory
  main.tf, index.ts, playbooks, modules
  .iac-studio.json
  terraform.tfstate when present

Repository layout

Path	Purpose
`cmd/server`	Single binary entrypoint and embedded production frontend.
`internal/api`	HTTP router, request validation, project handlers, command handlers, and API tests.
`internal/iac`	IaC parsing, generation, security, drift, modules, promotion, export, and tool integration.
`internal/ai`	AI providers, prompts, topology, agent, RAG, and tool calling support.
`web/src`	React UI, canvas, panels, API client, hooks, and tests.
`docs`	This static GitHub Pages documentation site.
`.github/workflows`	CI, release, Docker, and Pages publishing workflows.

Project state file

IaC Studio stores UI metadata in .iac-studio.json. It keeps canvas coordinates, edges, environment metadata, selected layout, and other non-IaC state separate from generated Terraform, OpenTofu, Ansible, or Pulumi files.

Development

Prerequisites are Go 1.25+, Node.js 20+, npm, and the IaC CLIs you want to execute locally.

Install dependencies

make deps

Run hot reload

make dev

Run tests

make test

Build binary

make build

Cross-compile releases

make release

Build Docker image

make docker

Development server ports

make dev runs the Go backend on :3001 and the Vite frontend on :5173. The production binary serves the built frontend and API from one process.

Deployment and Releases

CI

Pull requests and main branch pushes run Go tests, frontend tests, and production builds.

Release tags

Tags matching v* trigger cross-platform release artifacts and checksums.

Docker

Main branch and release tags publish container images with Terraform and OpenTofu installed.

GitHub Pages

The Pages workflow uploads docs/ as a static artifact and deploys it to the project site.

Troubleshooting

The app screen is blank or black

Open the browser console first. Most blank screens are frontend runtime errors. Refresh after pulling the latest branch, then check the console stack trace for a component and line number. If the error mentions null or undefined data, try reloading the project from disk or opening a fresh project.

Port 3000 is already in use

./bin/iac-studio --port 3002

Ollama is unavailable

Start Ollama and verify the model exists.

ollama list
ollama pull qwen2.5-coder:7b

Terraform, OpenTofu, or Ansible command fails

Confirm the CLI is installed and available on PATH. Docker images include Terraform and OpenTofu, but local binaries depend on your machine.

Apply is blocked by policy

Review the Policy Studio findings. Fix blocking issues when possible. Only acknowledge a block when you deliberately accept the risk for the current operation.

Docker cannot write project files

Check the mounted host directory permissions. The default container command writes projects under /projects, which should be backed by a writable host directory.

FAQ

Does IaC Studio require a cloud account?

No. The app runs locally. Cloud credentials are only needed when you run real IaC commands that require provider access.

Does it send telemetry?

No telemetry is built into the app. External AI providers receive only the requests you choose to send to them.

Can I use it without AI?

Yes. The visual editor, parser, generator, command runner, policy, scan, module, and export paths can be used without AI.

Where are projects stored?

By default, projects live in ~/iac-projects. Override this with --projects-dir.

Can I commit generated files?

Yes. IaC Studio writes normal IaC files. Commit them the same way you would commit hand-written Terraform, OpenTofu, Ansible, or Pulumi projects.