Architecture

Independent desired-state and interaction automation layer for EVE-NG (not an official EVE-NG product). Git holds desired lab state. eve-iac-agent is the only process that talks to native EVE. The VSIX Cockpit is a derived view, never a third source of truth.

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

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

Engineering internals (ownership, epochs, provider contract): repository docs/architecture/. This page is public HLD only. Product positioning: Why EVE IaC?.

Sources of truth

Source Role
Repository Desired truth (topology.yml, configs/**, marker, presentation)
EVE / Agent Runtime truth (native objects, running/stopped, consoles, live link quality/suspend)
Cockpit / Tree Derived presentation

Logical IaC keys (n_1, network keys) survive redeploy. Native EVE ids do not.

Git is the desired-state source. Applications are explicit (plan, then deploy/reconcile). There is no pull-based continuous reconciler. See Git-driven workflow.

Reconcile (to_eve)

  • Desired → managed runtime.
  • Independent live-safe changes apply even when other rows need a stop or are unsupported.
  • Remaining requires_stop work needs explicit confirmation plus a matching plan identity.
  • unsupported changes stay pending. Partial convergence is normal.
  • Deploy creates the managed lab the first time. Later edits use Reconcile, not Deploy.

Pull from EVE (from_eve)

Runtime → Local Git files. Never stops, starts, or mutates runtime. Confirm does not change that. Import is a different first-adoption operation.

Startup configs

configsets.<set>.<node> is the library. nodes.<node>.configset is the boot selector. They are independent.

AI

Mutate topology and configs through MCP/API tools. Do not filesystem-edit topology.yml, eve-presentation.yml, or configs/**. Humans may still edit those files in VS Code.

CURRENT: action classification uses a temporary policy provider. FUTURE: the same contract, backed by a Go EVE API. That future provider is not implemented today.