> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# Install EVE-OS onto ESXi

> How to install one or more EVE-OS virtual instances onto a VMware ESXi hypervisor, enabling multiple nodes to run on a single physical machine.

## Introduction

Run EVE-OS as one or more virtual machines on VMware ESXi to operate multiple independent nodes on a single physical host. Any instance of EVE running on a hypervisor as "virtual EVE" or a "virtual node" is referred to as virtual EVE (vEVE).

A virtual instance of EVE-OS functions identically to a physical one, with two minor differences:

* IOMMU functionality can only be accessed by one virtual node at a time on a given host.
* Virtualization adds some overhead, which may affect performance-sensitive applications.

This procedure assumes familiarity with ESXi. For ESXi-specific operations not covered here, refer to VMware's official documentation.

## Prerequisites

* EVE-OS version 9.4.0 or later.
* ESXi server 7.0 Update 3 or later.
* PowerShell/PowerCLI (recommended for the onboarding step).

## Add VM Hardware to Your Enterprise

1. Log in to ZCLI. See [Get Started With ZCLI](https://zededa.mintlify.site/zcli-reference/get-started.md) for authentication steps.
2. Create a `hardware.json` file for an ESXi VM on your local machine. See the [Hardware Models guide](https://help.zededa.com/hc/en-us/articles/31467631543707-Create-a-Hardware-Model) for file format details.
3. List your Docker containers.

```text theme={"dark"}
docker ps
```

4. Observe the output from the previous command. Copy the ID of your ZCLI container, shown in the first column of the output. For example:

```text theme={"dark"}
4fbeb231cb3b   zededa/zcli:9.4.0   "/bin/bash --rcfile ..."   3 minutes ago   Up 3 minutes   compassionate_blackburn
```

5. Copy your `hardware.json` into the ZCLI container's root directory.

```text theme={"dark"}
docker cp PATH_TO_hardware.json DOCKER_CONTAINER_ID:/root
```

6. Create a brand in Edge Infrastructure Services called VMware.

```text theme={"dark"}
zcli brand create VMware --title=VMware
```

7. Create a hardware model called `7.0u3guest` using your `hardware.json` file.

```text theme={"dark"}
zcli model create 7.0u3guest --title=7.0u3guest --brand=VMware --hardware-details=/root/hardware.json
```

## Get an EVE-OS ISO

Pull the EVE-OS ISO for your target version from Docker Hub. The following example uses version 9.4.0 for AMD64.

```text theme={"dark"}
docker pull lfedge/eve:9.4.0-kvm-amd64
```

Upload the ISO to a ZEDEDA Cloud datastore or your vSphere library. You will point to it when creating the VM.

## Configure a Network Port Group on ESXi

Create a new port group with the following security settings set to **Accept**:

* Promiscuous mode
* MAC address changes
* Forged transmits

![ESXi port group security settings showing Promiscuous mode, MAC address changes, and Forged transmits all set to Accept](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/images/esxi_portgroup.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=6c8f94346c677e1ceecc79b9bd8b1c95)

## Create the Virtual Machine

Complete the following sub-sections in order to create the vEVE VM.

### Create a new VM

![ESXi new VM creation dialog](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/images/esxi_new_vm.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=eb869b5c74b345e0bed6105e062d1884)

### Select Guest OS family and Guest OS version

![ESXi Guest OS family and version selection showing Linux guest type](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/images/esxi_guest.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=7d3f65eea5c87c5a7b1ed691f74718b3)

### VM storage

Select a datastore to host the vEVE VM.

![ESXi VM storage datastore selection](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/images/esxi_vm.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=c1555bf6cebc28e3272fbe3cb23ee74f)

### CPU settings

Enable the following options in the CPU section: **Hardware virtualization**, **IOMMU**, and **Performance counters**.

![ESXi CPU settings with Hardware virtualization, IOMMU, and Performance counters enabled](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/images/esxi_cpu.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=96d5a53a31c7df1f6b7867f03546c120)

### Network settings

Assign the port group created in the previous section.

![ESXi network settings showing port group assignment](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/images/esxi_network.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=5b2efa6410b45b0ce7ee7c715ac95971)

### CD-ROM settings

Select the EVE-OS ISO (created in the previous section) for the guest installation.

![ESXi CD-ROM settings showing EVE-OS ISO selected](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/images/esxi_cdrom.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=efc27a128c7b558f06765827c4615e4a)

### VM options

Ensure **Enable UEFI secure boot** is **not** selected.

![ESXi VM options showing Enable UEFI secure boot unchecked](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/images/esxi_vm_options.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=25dfd163155efefaddbff9eaa4b2e540)

## Get the Hardware Serial Number (macOS)

When onboarding a vEVE node, you need its hardware serial number derived from the VM UUID. The following procedure uses `brew` and is written for macOS. For other platforms, use the equivalent PowerShell installation method.

1. Install PowerShell.

```text theme={"dark"}
brew install --cask powershell
```

2. Install PowerCLI. Enter `y` at the prompt.

```text theme={"dark"}
PS /Users/USERNAME Install-Module -Name VMware.PowerCLI -Scope CurrentUser
```

3. Configure PowerShell to ignore invalid certificates (if applicable). Enter `y` at the prompt.

```text theme={"dark"}
PS /Users/USERNAME Set-PowerCLIConfiguration -InvalidCertificateAction Ignore
```

4. Connect to the ESXi or vSphere server. Enter your credentials at the prompt.

```text theme={"dark"}
PS /Users/USERNAME connect-viserver -server ESXI_OR_VSPHERE_ADDRESS
```

5. Get the vEVE VM UUID.

```text theme={"dark"}
PS /Users/USERNAME $s = (Get-VM VM_NAME | %{(Get-View $_.Id).config.uuid}).Replace("-","")
```

6. Verify that the UUID was saved correctly.

```text theme={"dark"}
PS /Users/USERNAME echo $s
```

The output looks like: `564ded02f75268f111428e7cece8db81`

6. Format the UUID as a hardware serial number.

```text theme={"dark"}
$Uuid = "VMware-"
for ($i = 0; $i -lt $s.Length; $i += 2) {
  $Uuid += ("{0:x2}" -f [byte]("0x" + $s.Substring($i,2)))
  if ($Uuid.Length -eq 30) {$Uuid += "-"} else {$Uuid += " "}
}
PS /Users/USERNAME $Uuid.TrimEnd()
```

Save the output. It looks like:

```text theme={"dark"}
VMware-56 4d f2 69 73 8c b3 72-5e 27 cf 93 40 26 6e f6
```

## Onboard the Node Using ZCLI

Use the following PowerShell script to onboard a single vEVE node. Replace `ONBOARDING_KEY` with the node's onboarding key before running.

```text theme={"dark"}
param($viserver,$vmname,$model,$project)
$onboardingkey="ONBOARDING_KEY"
if($global:defaultviserver -eq $null) {
  connect-viserver -server $viserver
}
$s = (Get-VM $vmname | %{(Get-View $_.Id).config.uuid}).Replace("-","")
$Uuid = "VMware-"
for ($i = 0; $i -lt $s.Length; $i += 2) {
  $Uuid += ("{0:x2}" -f [byte]("0x" + $s.Substring($i, 2)))
  if ($Uuid.Length -eq 30) {$Uuid += "-"} else {$Uuid += " "}
}
$serialnumber=$Uuid.TrimEnd()
$containerid=docker ps | grep -i 'zededa/zcli' | awk '{print $1}'
docker exec -t $containerid zcli edge-node create $vmname \
  --onboarding-key=$onboardingkey --serial=$serialnumber --model=$model \
  --project=$project --network=eth0:management:defaultIPv4-net
Start-Sleep -Seconds 2
docker exec -t $containerid zcli network-instance create defaultLocal-$vmname \
  --edge-node=$vmname --kind=local --ip-type=v4 --default --port=Uplink
docker exec -t $containerid zcli edge-node activate $vmname
```

To run the script:

1. Log in to ZCLI. See [Get Started With ZCLI](https://zededa.mintlify.site/zcli-reference/get-started.md) for authentication steps.
2. Save the script as `onboardveve.ps1`.
3. Run the script, replacing the placeholder values with your environment details.

```text theme={"dark"}
./onboardveve.ps1 -viserver VCENTER_OR_ESXI_IP -vmname VM_NAME -model 7.0u3guest -project PROJECT_NAME
```

## Next Steps

> [card] [Onboard Nodes](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/onboard-nodes.md)
>
> Complete onboarding for your virtual nodes.

> [card] [Get Started with ZCLI](https://zededa.mintlify.site/zcli-reference/get-started.md)
>
> Reference for ZCLI authentication and commands.