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	What it is	How it moves
Infrastructure as Code	Git files (topology.yml, configs/)	Validate → plan → reconcile
Interaction as Code	Consoles, exec/wait/run, OOB SSH, generated inventories, live link quality / suspend, HTML5 capture, traffic matches	Happens to the running lab. Not a contract cell.

Engineering internals (ownership, epochs): repository docs/architecture/. This page is public HLD. Positioning: Why EVE IaC?. The reconcile machine: Plan / reconcile.

Sources of truth¶

Source	Role
Repository	Desired truth (topology.yml, configs/**, marker, presentation)
EVE / Agent	Runtime truth (native objects, running/stopped, consoles, live quality/suspend)
Cockpit / Tree / Lab canvas	Derived presentation. The canvas is not Open Lab and does not write the live EVE canvas

Logical IaC keys (n_1, net_1 / net_<type>, filter_1, t_1) survive redeploy. Native EVE ids do not. name: (LAN) is a display label, never the map key.

Applications are explicit. There is no pull-based continuous reconciler. See Git-driven workflow.

Reconcile¶

Reconcile is the desired-state machine. It is not a merge, not “apply the YAML anyway”, and not background GitOps.

     desired (Git)                         runtime (EVE)
  topology.yml, configs/                managed lab objects
            \                                 /
             \         eve-iac-agent         /
              \        HTTPS :8787          /
               \                           /
          validate  →  plan  →  reconcile

YAML is complete desired state. An option the node template owns, when absent from the file, means that template's default. The same default written explicitly is that value. An explicit empty string stays empty when the contract allows it. icon, image, and sat follow that rule: omitted sat and sat: -1 are any. Plan and reconcile compare this effective lab with the lab EVE stored, through one codec. Pull from EVE does not copy those defaults back into Git. An omitted boot selector stays “no intent”.

Policy lives in the agent contract (to_eve only). VSIX, MCP, and CLI display classification / obligations. They do not decide them. EVE never returns a Cell.

Two directions¶

	to_eve (Reconcile)	from_eve (Pull from EVE)
Authority	Local YAML	Managed lab (reproducible fields)
Mutates	EVE	Git files only
Contract obligations	Yes	No — repository sync
Stop / wipe / start	After confirm + matching plan_identity	Never
Presentation	Not replayed	May rewrite the local sidecar from live

Omitted direction is to_eve. from_eve is not Import. Wire values: Directions.

Three answers a plan can give¶

Classification	Meaning	Reconcile to_eve
live_applicable	Safe on current runtime	Apply now — only if the plan has no unsupported row
requires_stop	Reachable after an exact-node stop	Wait. Confirm is “this examined plan”, bound to plan_identity
unsupported	Unreachable in-place (change the YAML)	Zero EVE writes. The plan stays inspectable.

requires_stop is not unsupported. Partial convergence (pending_stop) is the live-safe pass with stop work left. An unsupported row is not partial: nothing ran.

Deploy vs later edits¶

Operation	When
Deploy	First creation of the managed lab
Reconcile to_eve	Every later desired-state change
Import	First adoption of a source EVE lab (then reconcile the managed copy)
LOAD	Attach. No deploy / reconcile / destroy

Outside this machine¶

Consoles, exec/wait/run, OOB SSH, generated inventories, live link quality/suspend, capture, and traffic: Interaction as Code. Operator schematic: Lab canvas. OOB and inventory: OOB SSH, Inventory export. Presentation restore: full IMPORT deploy/recreate only.

Startup configs¶

configsets.<set>.<node> is the library. nodes.<node>.configset is the boot selector. They are independent. Selector create is not node create. Upload / selector put / wipe wait until the node exists and is bound. Reconcile creates a named library YAML adds and deletes one YAML drops. default is the built-in store (id 1), not that library.

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.