EVE IaC for EVE V7 - Complete User Manual

This manual covers the operator-facing features of EVE IaC 0.9.2 for Visual Studio Code and Cursor with EVE V7. It follows the business lifecycle of a lab: connect, acquire, design, validate, deploy, operate, synchronize, and retire.

EVE IaC is an independent open-source project, not an official EVE-NG, Visual Studio Code, or Cursor product.

References: documentation, GitLab repository, releases.

Screenshots were captured from a live EVE V7 workspace.

1. Operating Model

Responsibility Scope Source of truth
Infrastructure as Code Nodes, networks, links, positions, startup configs, presentation Git under IaC/<lab>/
Interaction as Code Consoles, runtime state, live link quality, suspension, capture, traffic Running EVE V7 lab
Automation OOB SSH files and generated Ansible or Netmiko inventories Local .eve-iac/oob/ and .eve-iac/inventory/. Neither directory is committed

The extension communicates with eve-iac-agent over HTTPS, normally on TCP port 8787. The agent runs on EVE V7 and uses the local EVE API.

Recommended workflow:

  1. Install the agent and extension.
  2. Establish a trusted connection.
  3. Create, import, or load a lab.
  4. Edit the desired state in Git.
  5. Validate and review the plan.
  6. Deploy or reconcile the managed lab.
  7. Operate nodes and consoles.
  8. Pull approved EVE changes back to Git.
  9. Commit the resulting files.
  10. Retire the managed lab when no longer required.

2. Installation

2.1 Requirements

Component Requirement
EVE server EVE V7, eve-iac-agent, HTTPS port 8787, required images/templates
Workstation Visual Studio Code or Cursor 1.85+, network access, EVE IaC VSIX
Recommended extension Red Hat YAML
Project A Git folder where IaC/<lab>/ can be created

The VSIX works on Windows, macOS, and Linux. The workstation does not need Go.

2.2 Install the agent

sudo dpkg -i eve-iac-agent_0.9.2-1_amd64.deb
sudo systemctl status eve-iac-agent
curl -k -sS https://127.0.0.1:8787/api/v1/health

The service must report active (running). Record the TLS fingerprint:

sudo openssl x509 -noout -fingerprint -sha256 \
  -in /opt/unetlab/addons/eve-iac-agent/tls.crt

If absent, check /opt/unetlab/go/server.crt.

2.3 Install the extension

  1. Install Visual Studio Code (1.85 or later) if the workstation does not already have it.
  2. Download eve-iac-client-0.9.2.vsix from the GitLab Release.
  3. Open Extensions > More Actions > Install from VSIX....
  4. Select the VSIX and reload if requested.
  5. Open the Git project folder.
  6. Select EVE IaC in the Activity Bar.

Use one owner window per session. A second IDE window can receive session_already_active.

3. Secure Connection

Open EVE IaC > Connection > Configure Connection and enter the agent URL, EVE username, and EVE password. Use https://<EVE-host>:8787; plain HTTP is rejected.

On first contact, compare the displayed SHA-256 fingerprint, certificate subject, and Subject Alternative Names with the server certificate. Trust stores that certificate in the IDE. Later agent connections accept the server only when the live leaf has the same SHA-256 fingerprint. The PEM is not installed as a CA, and the agent connection does not use the workstation trust store. A later certificate change produces tls_pin_mismatch and requires a new trust decision.

Passwords may be stored in IDE Secret Storage. They are never written to settings.json, Git, or MCP configuration. The extension uses an opaque agent session token instead of exposing EVE cookies.

Connected EVE V7 agent

Connection status, endpoint, authenticated identity, configuration, and disconnect controls.

Control Purpose
Configure Connection Change URL, account, password, or certificate trust
Sign In Authenticate to the configured agent
Disconnect Close the current IDE session
Clear Saved Credentials Remove stored credentials and secret material

Settings include eveIac.agentUrl, eveIac.username, and eveIac.labPath. The password is intentionally not a normal setting.

4. Acquire a Lab

Choose the mode according to topology ownership.

Business need Command Mode Ownership
Build from Git Create Lab create EVE IaC owns the managed lab
Adopt an existing lab as intent Import Lab import Source is immutable; intent only; deploy is separate
Operate without managing design Load Existing Lab (Read-Only Topology) load EVE owns the topology

Selecting a lab changes context only. It does not start, stop, deploy, or delete anything.

Lab acquisition controls

4.1 Create Lab

Creates:

IaC/<lab-name>/
  .eve-iac.yml
  topology.yml
  configs/

The marker records mode: create. An existing topology.yml is not overwritten.

4.2 Import Lab

Import reads an existing EVE lab and writes its Git intent, including supported presentation data. It records the source as immutable and the managed path for a later deploy. It does not create or change any EVE lab.

The Source path is never mutated. Deploy and Reconcile affect only Managed, and only after that lab exists. Import is initial adoption; Pull from EVE is later synchronization.

4.3 Load Existing Lab

LOAD creates only the local marker required to attach to an existing lab. It allows Inspect, Open Lab, start/stop/wipe, consoles, and live link actions. Validate, Plan, Deploy, Reconcile, Pull, and managed deletion are unavailable because EVE IaC does not own the topology.

4.4 Migrate an older project

Migrate Root Project into IaC/ converts a root-level .eve-iac.yml project to IaC/<lab>/. Review the Git diff immediately afterward.

5. Cockpit: Detailed Reference

The sidebar is the operational Cockpit. It contains Connection, Labs, and Current Lab. The status bar repeats connection and active-lab context.

EVE IaC cockpit overview

5.1 Connection

This section shows agent state, endpoint, authenticated EVE identity, connection controls, and AI integration status. Header icons provide configuration, disconnect, and the complete action menu.

5.2 Labs

The first rows start Create, Import, and Load workflows. The nested Labs group lists local projects discovered under IaC/, with each lab's observed runtime state. Selecting a row only changes active context.

5.3 Current Lab identity

Row Meaning
Active lab Current context and observed runtime state
Source Immutable source for imported or loaded projects
Managed Only EVE path topology commands may mutate
topology.yml Desired-state file; M indicates a modified file
Live config apply Per-lab authorization for unprompted live changes

For imported labs, verify that Source and Managed are different before Deploy or Reconcile.

5.4 IaC group

Action Behavior
Plan Computes Git-to-EVE differences without changing EVE
Reconcile Corrects supported drift in the managed lab
Deploy to EVE Creates or updates the managed topology from Git
Pull from EVE Imports approved EVE-side changes into project files

Plan is the routine approval checkpoint and should be reviewed like an infrastructure change.

The IaC group is hidden in LOAD mode. Automation and Runtime stay.

5.5 Automation group

These three rows are on the current lab, including a LOAD lab. They do not edit topology.yml.

Action Effect
Prepare OOB SSH Writes .eve-iac/oob/ for this agent session: ssh_config, the user key, known_hosts, session_token, and agent_context. The workstation does not listen. Requires a signed-in session.
Stop OOB SSH Revokes that generation with the stored bearer. Deletes the directory when the agent accepts the revoke or rejects the bearer. An unreachable agent leaves the files in place.
Generate Inventory Asks for Ansible or Netmiko, then writes .eve-iac/inventory/. Uses this extension's OOB proxy. Does not call the agent. Prepare OOB SSH first.

The SSH user in those files is eve-oob. That is not the agent login. Field-by-field behavior: OOB SSH and Inventory export.

5.6 Runtime group

Action Scope Effect
Open Lab Lab Opens the EVE V7 HTML5 topology in the IDE
Lab Canvas Lab Opens the local schematic. Lab canvas
Start All Lab Starts every node
Stop All Lab Stops every node and interrupts sessions
Wipe All Lab Clears runtime state for every node

Stop All and Wipe All are broad actions. Confirm the Current Lab heading first.

5.7 Nodes group

Each row shows node key, display name, and runtime state. Expand a node for targeted actions.

Per-node controls

Node action Purpose
Open Console Opens the template's text or graphical console
Open Startup Config Opens the selected config-set file
Startup Config status Shows config set, expected path, and file presence
Start Starts this node
Stop Stops this node
Wipe Clears this node's runtime state

Selected node rows also show inline action icons. Hover an icon for its tooltip.

5.8 Header actions and full menu

The Current Lab header offers Open Lab, Inspect / Refresh, and the full EVE IaC menu.

Complete action menu

Use the menu when a tree group is collapsed or an action is outside the current scroll position.

6. Project Files and Editing

IaC/<lab>/
  .eve-iac.yml
  topology.yml
  eve-presentation.yml        # optional
  configs/
    default/
      n_1.cfg
    <alternate-configset>/
      n_1.cfg

.eve-iac.yml records mode and EVE paths. topology.yml is desired state. eve-presentation.yml carries supported visual metadata. configs/<configset>/ stores startup configurations.

6.1 Schema-aware YAML

The extension registers the EVE IaC schema. With Red Hat YAML installed, the editor provides validation, hover help, completion, and field documentation.

Topology editor and toolbar

The editor toolbar exposes Validate, Open Changes, Plan, Reconcile, Pull from EVE, and Open Lab.

Use Fill Template Defaults and Fill Network Defaults to insert supported defaults, then review generated values before committing.

A node normally defines a stable key such as n_1, display name, template, image, position, config set, and template attributes. Links reference stable keys, not display names. Renaming a deployed key can be interpreted as deleting one node and creating another.

Networks define shared segments. Links define endpoint pairs and optional VLAN attributes. Validate interface names against the EVE template.

6.3 Configuration sets

configset selects configs/<configset>/<node>.cfg. Use none when no startup configuration should be applied. Alternate sets support exercises and staged scenarios without duplicating topology.

7. Validate, Plan, Deploy, Reconcile

Validate

Validation checks schema and domain rules, including references, endpoint definitions, supported values, and configuration paths. Run it after changing keys, templates, images, interfaces, networks, links, or config sets.

Plan

Plan is read-only. Review creations, removals, node replacement, link changes, startup config changes, and Source/Managed paths. An unexpected removal is a reason to stop.

Deploy to EVE

Recommended sequence:

  1. Save all files.
  2. Validate.
  3. Plan.
  4. Review destructive operations.
  5. Deploy.
  6. Inspect / Refresh.
  7. Open Lab and confirm the result.

Reconcile

Reconcile repairs supported drift when Git must remain authoritative. A node option the template owns, when left out of topology.yml, is that template's default: if the lab still has another value, reconcile sends the default. An empty icon: "" is an empty icon when the contract allows it. Pull from EVE does not write those defaults back into Git. To preserve an intentional EVE-side change, use Pull from EVE instead. Details: Plan / reconcile.

Live Config Apply

Toggle Live Config Apply controls a per-lab safety gate. When OFF, MCP-driven live reconcile or wipe must ask first. Keep it OFF for shared or production-like labs. Enable it only for a controlled automation window.

8. Operate in EVE V7

Show Lab Canvas draws the lab from public project JSON beside the Cockpit. Pointer, select, and area zoom are always available. Edit opens a local authoring session with an empty form. The hint is "Select an object, or choose a tab to add one." A node, network, or link click fills that object's form. A tab opens an add form. Details: Lab canvas. Open Lab opens the EVE V7 HTML5 interface inside the IDE, preserving the Cockpit beside the topology.

EVE V7 topology opened from the Cockpit

The embedded EVE view remains interactive. The example shows live OSPF traffic filters and counters.

Use Inspect / Refresh after out-of-band changes, runtime actions, reconnection, or deployment. It refreshes observed state without changing the lab.

Start boots from configured startup state. Stop terminates the process while preserving its state. Wipe clears runtime state so the next start follows startup configuration again. Wipe does not delete the topology.

Export running config (node menu and canvas selection, next to Wipe) copies the running NOS configuration into an existing EVE startup-config set. The quick pick offers default, the configset names in topology.yml, and a typed name for a set that exists only on the live lab. The confirmation names the set and the nodes. The command does not write topology.yml or configs/**. An unknown set is not created. LOAD mode refuses it. After the export, Pull from EVE is still a separate step if you want that blob in Git.

9. Consoles and Clipboard

For serial/Telnet-style nodes, Open Console creates a tab in the EVE Console panel. Multiple sessions can remain open as tabs.

Integrated EVE text console

The connection indicator confirms transport status. Closing a console tab does not stop the node. Tabs can be split into groups, moved between groups, and resized. A capture tab does not replace the node console, and closing it does not stop the capture container.

RDP, VNC, and other graphical console types use the supported embedded or external workflow for the template and workstation.

Prepare OOB SSH is the SSH path onto that same console. It is in the Automation group, not on the console tab. Consoles.

Paste Local Clipboard sends local clipboard text to the active supported console. On a graphical console the text is normalized for a US keyboard (NFKC, line endings, unusual spaces, zero-width characters) and a character with no US-keyboard stroke is skipped. When the node has delkey enabled, a text console maps Delete (0x7F) to Backspace (0x08). Verify the target node and prompt before pasting. Do not expose secrets unintentionally.

10. Pull Changes from EVE

Use Pull from EVE when a managed EVE change is intentional and should become Git state:

  1. Inspect / Refresh.
  2. Pull from EVE.
  3. Review the Git diff.
  4. Validate the imported representation.
  5. Remove transient or accidental changes.
  6. Commit approved files.

Pull never mutates the immutable import source. It is unavailable in LOAD mode.

Live-link functions apply runtime behavior without rewriting topology intent. Supported operations are inspection, delay/jitter/loss/rate quality, and suspend/resume. The lab canvas also shows traffic matches from the agent stream and can start an HTML5 capture on a node interface. See Lab canvas.

Use these for demonstrations, incident exercises, and fault injection. Document a scenario separately when it must be reproducible.

12. AI and MCP Integration

Command Purpose
AI Integration Opens integration workflow and status
Configure Claude Code Writes supported Claude Code MCP configuration
Configure Codex Writes supported Codex MCP configuration
Remove Claude Code Configuration Removes configuration created by EVE IaC
Remove Codex Configuration Removes configuration created by EVE IaC

Cursor may use dynamic in-session MCP registration rather than a static file. The same safety model applies to AI actions. Never put the EVE password in prompts or MCP files.

13. Delete and Retire

Delete Lab removes the EVE IaC managed lab according to ownership rules. It must not delete an immutable import source.

Before deletion, confirm the active lab, Source and Managed paths, pull and commit required changes, and stop dependent consoles or automation. Wipe All clears runtime state; Delete Lab removes the managed topology.

14. Complete Command Reference

Command Effect Availability
Show Actions / Show Sidebar Navigation only Always
Configure Connection / Sign In / Disconnect Session management As applicable
Clear Saved Credentials Removes stored secrets Always
Create Lab Creates managed project Connected
Import Lab Writes IaC intent; does not deploy Connected
Load Existing Lab Read-only topology attachment Connected
Select Active Lab Changes context only Local labs present
Open Topology Opens desired-state file CREATE/IMPORT
Validate / Plan Read-only analysis CREATE/IMPORT
Deploy / Reconcile Mutates managed topology CREATE/IMPORT
Pull from EVE Changes local files CREATE/IMPORT
Inspect / Refresh Refreshes observed state Active lab
Open Lab Opens embedded EVE UI Active lab
Show Lab Canvas Opens the local schematic Active lab
Start/Stop/Wipe All Lab runtime action Active lab
Start/Stop/Wipe Node Node runtime action Inspected node
Open Console Opens console session Inspected node
Prepare OOB SSH Writes .eve-iac/oob/ for this session Connected, active lab
Stop OOB SSH Revokes the OOB generation Active lab
Generate Inventory Writes .eve-iac/inventory/ Active lab, after Prepare OOB SSH
Open Startup Config Opens config file File available
Paste Local Clipboard Sends console input Active console
Toggle Live Config Apply Changes authorization state Active lab
Migrate Root Project into IaC/ Changes local layout Legacy project
Fill Template/Network Defaults Edits local topology Editor context
Configure/Remove Claude Code or Codex Changes local AI config Supported client
Delete Lab Deletes managed lab Owned managed lab

15. Troubleshooting

Agent disconnected

Confirm the service, test the health URL, check routing/firewall, then Sign In. Reconfigure if the endpoint or account changed.

TLS fingerprint mismatch

Do not bypass it. Verify whether the server certificate was intentionally renewed and compare its SHA-256 fingerprint before trusting the replacement.

session_already_active

Disconnect or close the previous owner window, then sign in from the intended workspace.

No active lab

Select a lab under Labs. If none appears, verify IaC/<lab>/.eve-iac.yml exists in the open folder.

IaC actions disabled

LOAD mode intentionally disables topology operations. Otherwise verify topology.yml exists and the agent is connected.

Unexpected deletion in Plan

Stop. Check active lab, Source/Managed paths, stable node keys, template/image values, and the Git diff.

Startup config not applied

Verify configset, file path, and Present: yes. Some changes require a node wipe before the next boot reads startup configuration.

Console does not open

Refresh, confirm the node is running, verify its console type, and check browser/webview or external handler permissions.

Embedded page paused

Dismiss the IDE notification covering the embedded browser; it can pause while a notification has focus.

16. Operator Checklists

Before deployment

  • Correct active lab and EVE V7 server
  • Source and Managed paths verified
  • Files saved; Validate successful
  • Plan and destructive changes reviewed
  • Required images/templates present
  • Git working state understood

Before runtime maintenance

  • Correct node or lab scope
  • Console users informed
  • Startup config retained in Git. If the useful configuration is the running one, Export running config into an existing set before Pull from EVE
  • Stop/Wipe impact understood
  • Live Config Apply authorization appropriate

After an EVE-side design change

  • Inspect / Refresh completed
  • Pull completed and Git diff reviewed
  • Imported files validated
  • Approved state committed

Before retirement

  • Required changes pulled and committed
  • Managed path confirmed
  • Immutable source confirmed untouched
  • Consoles and automation stopped
  • Delete confirmation reviewed