> For the complete documentation index, see [llms.txt](https://docs.vex-nx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vex-nx.com/getting-started/install-from-usb-bare-metal.md).

# Install from USB (bare metal)

![Install from USB path (diagram)](https://1807546539-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhgHCHWL3861o2DBW53aA%2Fuploads%2FHT4CQZkYay7hGaifgNDB%2Fve20261112v5-diagram-install-usb.png?alt=media)

## Goal

Install VEX-NX on a **physical server** (or a carefully created VMware VM that boots the bare-metal ISO) with native KVM for heavy nested labs (vJunos, nested ESXi, large QEMU topologies).

Day-1 software matches the OVA (web UI, SSH, templates, licence policy, hostname **VEX-NX**, TLS name **vex-nx.local**). Hardware day-0 differs: real NICs + installer network screens instead of the OVA three-NIC wizard.

## What you need

| Item    | Detail                                                                             |
| ------- | ---------------------------------------------------------------------------------- |
| Media   | `vex-nx-<version>-baremetal-amd64.iso` (verify SHA256 from your release notes)     |
| USB     | 8 GB+ stick (will be wiped) **or** a VM CD/DVD attached to the ISO                 |
| CPU     | VT-x / AMD-V enabled in BIOS/UEFI                                                  |
| Disk    | Target disk will be **erased** (80 GB+ recommended; more for image libraries)      |
| Console | Local console, IPMI / iDRAC / iLO, or VM console during install                    |
| Network | Know whether management will be DHCP or Static (IP, prefix/mask, gateway, **DNS**) |

Day-1 credentials (forced password change):

| Access | User  | Password |
| ------ | ----- | -------- |
| Web UI | admin | vexnx    |
| SSH    | vexnx | vexnx    |

***

## Path 1 - Physical server (USB)

### 1. Flash the ISO

1. Download `vex-nx-<version>-baremetal-amd64.iso`.
2. Write the USB with **Rufus** (mode **DD Image**) or **balenaEtcher**.\
   Do not use "ISO mode" in Rufus if it offers a hybrid warning that rewrites the image incorrectly.
3. Eject the USB safely.

### 2. Firmware prep on the server

1. Enter BIOS/UEFI.
2. Enable **VT-x / AMD-V** (and VT-d / AMD-Vi if offered).
3. Prefer **UEFI** boot for the installer USB.
4. If Secure Boot blocks the installer, try Secure Boot **off** for first install.
5. Set USB (or UEFI USB entry) first in the boot order for this install only.

### 3. Boot the installer

1. Insert USB and power on.
2. At GRUB, select **VEX-NX Bare Metal Installer** (or **VEX-NX Graphical Installer**).
3. Wait for the graphical installer (Calamares) to appear. Do not power off.

### 4. Calamares - step by step

Follow the on-screen pages. Typical order:

1. **Welcome** - continue.
2. **Location / keyboard** - set as needed.
3. **Storage / Partition** - select the disk to **erase** for VEX-NX.\
   Double-check you are not wiping the wrong disk.
4. **Users** - create the local account as prompted by the installer screens.
5. **Network** (if shown in your build):
   * Pick the **management** NIC
   * Choose **DHCP** or **Static**
   * For Static: IP, subnet/prefix, gateway, and **DNS** (DNS matters for any later pulls)
6. Confirm and start install.
7. Wait until install finishes. Current media is designed to **reboot** when done (Finish / restart).
8. Remove the USB when prompted (or change boot order back to the internal disk) so the next boot is from the installed system.

### 5. First boot after install

1. Boot from the internal disk (no USB).
2. Open the console. You should get the **management network** menu if network was not finalized:
   * **1** = DHCP (default after the countdown if you press nothing)
   * **2** = Static (no timeout while typing)
3. Wait for services / splash to finish. Note the management IP.
4. Browser: `http://<management-ip>/` - **admin** / **vexnx**
5. SSH: **vexnx** / **vexnx**

### 6. Post-install checks

1. [First login](/getting-started/first-login.md) - complete password change.
2. **Infrastructure** - confirm hostname, IP, Docker, and **KVM** (`ls -l /dev/kvm`).
3. Map lab clouds to real NICs if your server has multiple ports: [Networks and clouds](/getting-started/networks-and-clouds.md).
4. Import images and build a small lab: [First lab walkthrough](/labs/first-lab-walkthrough.md).

***

## Path 2 - VMware Workstation / ESXi booting the bare-metal ISO

Use this only when you intentionally install from the **ISO** inside a VM (not the OVA). The OVA path is simpler for VMware - see Install the OVA.

### Critical: do not use Easy Install

On VMware Workstation, **Easy Install** (yellow banner / "Install Ubuntu...") hijacks the guest and often leaves a **black screen with a blinking cursor**. VEX-NX uses Calamares, not stock Ubuntu auto-install.

### ESXi / Workstation console tips (keyboard and mouse)

1. Firmware: **UEFI**
2. Video memory: set **16 MB or higher** (4 MB often breaks the Calamares GUI / input)
3. Click inside the console so it has focus; try USB tablet device enabled
4. Prefer the **OVA** on hypervisors when possible - ISO-in-VM is a secondary path
5. Current ISO live image includes **open-vm-tools** and the VMware Xorg driver for Host Client / Workstation consoles

### Create the VM correctly (Workstation)

1. **File -> New Virtual Machine -> Custom (advanced)** (or Typical).
2. When asked for the installer disc: choose **I will install the operating system later**.\
   Do **not** select Ubuntu + auto-install / Easy Install.
3. Guest OS type: Linux -> **Ubuntu 64-bit** (label only).
4. Disk: **80 GB+** (thin is fine).
5. After the VM exists, open **Settings**:
   * **CD/DVD**: Use ISO image -> your `vex-nx-*-baremetal-amd64.iso`, **Connect at power on**
   * **Firmware**: **UEFI** (Options -> Advanced -> Firmware type = UEFI)
   * Memory **4 GB+**, CPUs **2+** (raise for labs)
   * Enable **Virtualize Intel VT-x/EPT** on Processors
6. Power on. You must see a **GRUB** menu for VEX-NX.\
   If you only see a black underscore and the yellow Ubuntu Easy Install banner, delete the VM and recreate with the steps above.

### ESXi VM booting the ISO

1. Create a new VM (Linux / Ubuntu 64-bit style), UEFI firmware.
2. Attach the bare-metal ISO to the CD/DVD, Connected.
3. Size disk/CPU/RAM as above; enable nested virt if you will run QEMU labs.
4. Power on to GRUB -> VEX-NX installer.
5. Complete Calamares as in Path 1, then disconnect the ISO and reboot from disk.

### After the GUI appears

Complete Calamares, allow reboot, remove/disconnect the ISO, then follow **First boot after install** above.

***

## Expected result

Same day-1 software as the OVA:

* Web: `http://<management-ip>/` - **admin** / **vexnx**
* SSH: **vexnx** / **vexnx**
* Hostname **VEX-NX** / TLS **vex-nx.local**
* Offline Docker seeds for FRR and Alpine on current media
* Host packages needed for Exact (QEMU) overlays (including `qemu-img`) on current ISO builds

***

## If it fails

| Symptom                                               | Fix                                                                                                                  |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| USB will not boot                                     | Use UEFI boot entry; try Secure Boot off; re-flash with Rufus **DD** mode                                            |
| Black screen / blinking cursor on VMware              | Easy Install was used - delete VM; recreate with **I will install the operating system later** + UEFI + ISO attached |
| Keyboard / mouse dead in Calamares (ESXi/Workstation) | Raise video memory to 16MB+; enable USB tablet; click console; use a current ISO with open-vm-tools                  |
| Partitions page empty / Next grey                     | Choose Erase disk (current media defaults to erase); if UI is blank, fix video/input first                           |
| GRUB never appears                                    | Wrong firmware (use UEFI); wrong ISO; CD not connected                                                               |
| Installer cannot find disk                            | Check SATA/NVMe controller in BIOS; for VMs use a supported virtual disk controller                                  |
| Static IP lost after reboot                           | Use a current ISO; set again under Infrastructure -> Management network; confirm Keep on console after GUI save      |
| Node Start: `qemu-img` not found                      | Media too old - reinstall from a current ISO that ships `qemu-utils`                                                 |
| FRR image missing / DNS errors                        | Set working DNS; `sudo vexnx-seed-docker`                                                                            |
| No KVM                                                | Confirm VT-x in BIOS / nested virt on VM; `ls -l /dev/kvm`                                                           |
| Finish hangs / no reboot                              | Wait; current builds auto-reboot - if stuck, use console logs under `/var/log` per support guidance                  |

***

## After install

1. [First login](/getting-started/first-login.md)
2. Infrastructure -> confirm **KVM** / `/dev/kvm`
3. [Management network](/getting-started/management-network.md) if you need Static later
4. [Networks and clouds](/getting-started/networks-and-clouds.md)
5. Install the OVA if you decide VMware OVA is a better fit than bare metal

## Related

* System requirements
* Troubleshooting
* FAQ


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.vex-nx.com/getting-started/install-from-usb-bare-metal.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.