EVE IaC

A new era in lab digital twins.

Infrastructure as Code for EVE-NG digital twins.

Define your lab in Git. Plan changes before they touch EVE. Reconcile, operate and automate from VS Code, CLI or code.

Capture · Edit · Plan · Review · Reconcile · Operate

CLI / SDKs / releases

Free · Open source · MCP · CLI · Python · TypeScript · Go

eve-iac Cockpit in VS Code: lab list, lab canvas, node console, and node editor

One workflow. From Git intent to running lab.

  1. Capture
  2. Edit
  3. Plan
  4. Review
  5. Reconcile
  6. Operate

EVE IaC does not continuously mutate your lab. Every change follows an explicit plan → review → reconcile cycle.

See the lab while you build it

The Lab Canvas turns topology.yml into a live digital-twin view. Edit the topology, inspect runtime state, open consoles and operate nodes without leaving the editor. Lab canvas

Nothing changes without a plan

Reconcile is fail-closed. Unsupported transitions are blocked, destructive operations remain explicit, and changes requiring downtime wait for confirmation. Plan / reconcile

AI agents, directly connected

MCP tools let coding agents inspect the lab, query runtime state, use consoles and operate nodes. Copilot, Cursor, Claude, Codex, and compatible local LLMs remain behind the same EVE IaC plan, policy and confirmation model. AI does not get a separate path to EVE-NG. AI / MCP

More than topology as code

Digital twin

Topology, runtime state, console access and operations remain connected.

Git-native

The YAML representation of the lab can live, branch, diff and review like code.

Human-controlled automation

Automation can generate a plan. A human — or another agent — can inspect and validate it before execution.

Capture existing labs

Already have an EVE-NG lab? Capture it into IaC instead of rebuilding it manually. Import an existing lab

Your lab becomes code

topology.yml is a portable, reviewable description of the lab — nodes, networks, links, configuration and intent. Interface names in this example come from the IOL and VPCS templates; confirm them on yours before you copy them. YAML

version: eve-iac/v1
name: iol-vpcs-minimal
nodes:
  n_1:
    name: SW1
    template: iol
    configset: default
  n_2:
    name: PC1
    template: vpcs
    configset: default
links:
  - endpoints:
      - { node: n_1, interface: e0/0 }
      - { node: n_2, interface: eth0 }

Diff it. Review it. Commit it. Reconcile it.

eve-iac plan ./lab prints one status line. eve-iac plan ./lab --json includes text, which the agent formats like the listing below. These rows illustrate a create and a change that must stop a running node. They are not a captured transcript. Plan / reconcile

eve-iac plan ./lab
direction=to_eve actions=2 exists=true plan_identity=<P>
#
plan ./lab direction=to_eve (1 bound node(s))
+ node n_2
~ node n_1  hardware_update  requires_stop node_running → requires_node_stop
1 create(s), 1 update(s), 0 prune(s), 0 blocked
#
eve-iac --yes reconcile ./lab --plan-identity <P>

Start where you work

First, connect EVE IaC to your EVE host

Install eve-iac-agent_0.9.0-1_amd64.deb on the EVE-NG host. The package is amd64 Debian and listens on HTTPS :8787. The workstation, CI, SDKs, and MCP clients talk to this agent. Compatibility

sudo dpkg -i eve-iac-agent_0.9.0-1_amd64.deb
sudo systemctl status eve-iac-agent

Operator

Use VS Code or Cursor to capture, edit, plan and operate EVE labs.

Operator guide

Workstation Visual Studio Code or Cursor 1.85 or newer. Windows 10/11 x64, macOS, or Linux x64 or arm64. A Git folder holds IaC/<lab>/.

EVE host eve-iac-agent from the step above. EVE-NG is the supported platform. Editions are not a published matrix.

DevOps

Use the CLI from Git pipelines and automation workflows.

DevOps guide

Python 3. The runner must reach the agent over HTTPS. Pin the CA in CI. Do not use the editor extension in a pipeline.

pip install eve-iac --index-url https://gitlab.com/api/v4/projects/eve-ng-dev%2Feve-iac/packages/pypi/simple
eve-iac --version

Developer

Build against the same HTTPS API using Python, TypeScript or Go.

Developer guide

Packages come from the GitLab release, not public PyPI, npm, or a Go proxy. Install packages

Open by design

EVE IaC is free and open source. The agent, CLI, SDKs and editor integration are developed in the open on GitLab.

Licensed under AGPL-3.0-only. eve-iac/v1 is the API being prepared for a public cut. Calls may still change until then. Community supported. Compatibility