How do you use eve-iac?

EVE IaC is a desired-state and interaction automation layer for EVE-NG. It combines Git-based Infrastructure as Code, safe reconciliation, and Day-0 console automation through one API. eve-iac is not an official EVE-NG product. Clients talk only to eve-iac-agent over HTTPS. They never call native EVE REST.

Define the infrastructure. Define how to interact with it. Automate both.

You are on eve-iac.io — the public documentation site. Source code and downloadable packages are on GitLab (not this domain).

Git / VS Code / CI / AI → eve-iac-agent (HTTPS :8787) → EVE-NG

Under the agent
Desired state Git YAML (topology.yml, configs/). Validate → plan → reconcile.
Interaction as Code Consoles (exec / wait / run) and live link quality / suspend.

Git is desired truth. EVE/agent is runtime truth. The VSIX Cockpit is a derived view — never a third source of truth. Why EVE IaC? · Architecture

Pick the path that matches how you work.

Operator

Use VS Code or Cursor to create, import, edit, and operate EVE-NG labs. You do not need to write code.

Get started as an operator

DevOps / CI-CD

Validate, plan, deploy, and reconcile labs from pipelines with the eve-iac CLI. Console automation supports Day-0 bootstrap before management IP or SSH exist.

Automate with eve-iac

Developer

Build integrations with the Python, TypeScript, or Go SDK, or call the HTTPS API.

Use the SDKs

What eve-iac is

Git files are desired state (topology.yml, configs/, .eve-iac.yml). The agent/EVE is runtime truth. The VSIX Cockpit is a derived view. Validate, plan, deploy, and reconcile are explicit operations. Importing an existing lab is not the same as pulling later changes with from_eve.

Important principles:

  • Persona tools, one API. The VSIX, CLI, and SDKs share eve-iac/v1.
  • Infrastructure vs interaction. Topology and startup-configs are desired state (Infrastructure as Code). Consoles, exec, wait, run, and live link quality/suspend are operational (Interaction as Code).
  • Desired state vs live state. Topology and startup-configs are desired. Consoles and inspect are operational. The Cockpit is derived, not authoritative.
  • Reconcile is fail-closed, then progressive. Any unsupported transition blocks all EVE writes. Independent live-safe changes apply only when the rest of the plan is reachable; remaining requires_stop work needs confirmation and a matching plan identity. Partial convergence is that leftover stop work, not “skip the hard rows”. See Architecture and Plan / reconcile.
  • Destructive work is explicit. Destroy, prune, wipe, replace, and classified stops require confirmation (--yes plus --plan-identity when stop work remains, the IDE prompt, or MCP confirm=true). --yes does not invent a plan identity.
  • TLS is pinned. Trust the agent certificate in the IDE, or pass --ca-file / ca_pem in automation. The CLI has no TOFU; optional --insecure is lab/dev only (never CI).
  • Git-driven, not autonomous GitOps. Git holds desired state. Pipelines push validate → plan → reconcile. There is no pull-based continuous reconciler. See Git-driven workflow.

Install quickly

Packages are on this GitLab project’s Package Registry and Releases — not public PyPI, npm, or a Go proxy. Copy the registry form, not the bare package name.

You Start here
VS Code / Cursor Install the VSIX (eve-iac-client-0.5.3.vsix)
Pipelines Install the CLI
Python pip install eve-iac --index-url https://gitlab.com/api/v4/projects/eve-ng-dev%2Feve-iac/packages/pypi/simple — install · SDK
Node npm config set @eve-iac:registry https://gitlab.com/api/v4/projects/eve-ng-dev%2Feve-iac/packages/npm/ then npm install @eve-iac/sdk — install · SDK
Go GitLab tarball + replace — install · SDK

Canonical names stay eve-iac / @eve-iac/sdk / github.com/eve-iac/eve-iac/sdk/go. Agent .deb, VSIX, CLI/Python wheel, npm, and Go tarball are published from this GitLab project (Package Registry + Release on tags), not from public indexes, the Marketplace, or a Debian archive. Local build: make pack-sdk deb vsix.

Project status

  • License: AGPL-3.0-only
  • Package version and API id are different. See versioning.
  • Candidate contract eve-iac/v1 is not a published freeze yet.
  • Compatibility — agent/client pairing, workstations, and what is not claimed.