> ## 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.

# Onboard nodes

> Add nodes to Edge Infrastructure Services using Ask ZEIA, Single-Use Installer, Onboarding Key, or Certificate.

Onboard a node when you want Edge Infrastructure Services to manage an edge device running EVE-OS. In the new UI, open **Infrastructure > Fleet > Nodes**, then select the contextual **+** create action in the lower-right corner. The same **+** pattern creates the resource for the page you are on. On the Nodes list, it starts node onboarding.

![Contextual plus create action in the lower-right corner of a list page.](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/assets/new-ui/nodes/contextual-plus-action.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=a823cfcf9bd8ef05a21f7f8e8f369f23)

The onboarding page heading is **Onboard Nodes**.

## Before You Start

Prepare the node and the platform objects it depends on.

| Requirement | Why it matters |
| - | - |
| Edge device | The device must be able to run EVE-OS. |
| EVE-OS plan | You can install EVE-OS during onboarding, use an already installed device, or install it later. |
| Cloud reachability | The management interface must reach Edge Infrastructure Services, commonly over port 443. |
| Project | The node must be assigned to one project. |
| Hardware model | The model should match the device so adapter and hardware configuration options are accurate. |
| Identity material | Use a certificate or an onboarding key with the device serial number. |
| Permissions | You have the SysManager or SysAdmin role in your enterprise. See [Manage Roles](https://zededa.mintlify.site/new-ui/infrastructure-services/administration/manage-roles.md). |

If you plan to deploy Applications from a datastore, make sure the node can reach that datastore from the deployment location.

### Name and identity uniqueness

Edge Infrastructure Services rejects an onboarding request that reuses an identity it already knows. Check the following before you create the node:

* The node **Name** must be unique within your enterprise, across all projects. If a node with the same name exists, the request fails with `Entry already exists`.
* An onboarding key and serial number pair, or an onboarding certificate and serial number pair, can register only one node. If that pair is already registered to a node, the request fails with `Duplicate Device configuration, already exists`.
* A device certificate can register only one node. If the certificate is already registered, the request fails with `Duplicate Device Certificate, already exists`.
* Supply either an onboarding key or an onboarding certificate, not both.

The serial number by itself does not need to be unique. Only its combination with the onboarding key or certificate must be.

If the matching node was off-boarded rather than deleted, the request does not fail. Edge Infrastructure Services re-onboards the node and reuses its previous identity. See [Off-board a Node](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/manage-node-lifecycle.md#off-board-a-node).

## Choose an Onboarding Method

The onboarding gallery offers four paths.

| Method | Use when |
| - | - |
| **Ask ZEIA** | You want guided help from ZEIA during onboarding. Not yet available. |
| **Single-Use Installer** | You want to create the node, flash the EVE-OS installer, and have it register automatically on first boot. Recommended for most operators. |
| **Onboarding Key** | You want to register the node using its serial number and an onboarding key UUID. Recommended for advanced users. |
| **Certificate** | You want to register the node using a hardware identity certificate. Recommended for advanced users. |

## Use Ask ZEIA

Ask ZEIA onboarding is not yet available. When available, this method will guide you through onboarding using ZEIA at the bottom of the console. Use Single-Use Installer, Onboarding Key, or Certificate in the meantime.

## Use Single-Use Installer

Single-Use Installer onboarding is organized as a **New Node** flow with the subtitle **Single-use installer onboarding**. The installer image is generated for the specific node after you create it, so the device registers automatically on first boot without requiring a serial number or certificate.

Choose this method when your environment does not support DHCP, when you need to provision an air-gapped node, or when you want to avoid writing manual JSON network configuration files. The installer contains a bootstrap configuration signed by Edge Infrastructure Services and can only be used once, making it more tamper-resistant than a hand-edited config file.

1. Open **Infrastructure > Fleet > Nodes**.
2. Select the contextual **+** create action.
3. On **Onboard Nodes**, select **Single-Use Installer**.
4. In **General**, enter **Name**, **Title**, and optional **Description**.
5. In **Assignment**, select a **Project**. Optionally select a **Hardware Model** to pre-configure network ports and IO adapters.
6. If you selected a hardware model, configure the **Network** and **IO Adapters** sections before continuing. If an adapter is bound to a network that uses static addressing, supply its IP details in the adapter row. See [Configure Per-Adapter IP Addresses](#configure-per-adapter-ip-addresses).
7. Select **Create Node**.
8. On the EVE-OS step, select **Generate Installer** for the appropriate architecture (AMD64 or ARM64).
9. When the image is ready, download it and flash it to a USB drive using ZFlash. See [Flash an EVE-OS Installer or Live Image](https://zededa.mintlify.site/new-ui/infrastructure-services/eve-os-installation/flash-eve-os-image.md).
10. Boot the edge device from the USB drive. The node registers with Edge Infrastructure Services automatically on first boot.
11. Select **Done** to return to Nodes.

After the device boots EVE-OS and reaches Edge Infrastructure Services, the node moves toward a registered or online state.

## Use Onboarding Key

Onboarding Key requires the device serial number and an onboarding key UUID, which are sent with the registration request instead of a generated installer image.

1. Open **Infrastructure > Fleet > Nodes**.
2. Select the contextual **+** create action.
3. On **Onboard Nodes**, select **Onboarding Key**.
4. In **General**, enter **Name**, **Title**, and optional **Description**.
5. In **Assignment**, select a **Project**. Optionally select a **Hardware Model**.
6. Select **Next** to proceed to **Registration**.
7. Enter the **Serial Number** and the **Onboarding Key** UUID. The Serial Number field accepts two kinds of serial:

   * **Hardware serial**: printed on the device label or available from the BIOS. You can enter this before EVE-OS is installed.
   * **Soft serial**: generated during EVE-OS installation. It is displayed when the install finishes and saved as a folder name in the INVENTORY partition of the install media.

   If you do not have a soft serial yet, expand **Don't have a soft serial number yet?** below the field. The panel instructs you to install EVE-OS first, then return to this step to complete registration with the serial the installation reports.
8. If you selected a hardware model, configure the **Network** and **IO Adapters** sections before continuing. If an adapter is bound to a network that uses static addressing, supply its IP details in the adapter row. See [Configure Per-Adapter IP Addresses](#configure-per-adapter-ip-addresses).
9. Select **Create Node**.

## Use Certificate

Certificate onboarding registers the node using its hardware identity certificate. Upload or paste the certificate in PEM format during the Registration step.

1. Open **Infrastructure > Fleet > Nodes**.
2. Select the contextual **+** create action.
3. On **Onboard Nodes**, select **Certificate**.
4. In **General**, enter **Name**, **Title**, and optional **Description**.
5. In **Assignment**, select a **Project**. Optionally select a **Hardware Model**.
6. Select **Next** to proceed to **Registration**.
7. Upload or paste the device hardware identity certificate in PEM format.
8. If you selected a hardware model, configure the **Network** and **IO Adapters** sections before continuing. If an adapter is bound to a network that uses static addressing, supply its IP details in the adapter row. See [Configure Per-Adapter IP Addresses](#configure-per-adapter-ip-addresses).
9. Select **Create Node**.

## Configure Per-Adapter IP Addresses

The **Network** section lists the adapters defined by the selected hardware model. Each adapter row binds a network from the node's project. Most networks (DHCP Client, None) need nothing else, but the two static addressing modes require IP details per adapter. The wizard blocks the Network step until every required field is complete, because Edge Infrastructure Services rejects node creation when an adapter bound to a static network has no IP address.

The same fields appear in all onboarding methods that include the Network section (Single-Use Installer, Onboarding Key, and Certificate).

### Static IP Networks

When an adapter is bound to a network whose IP Address Config is **Static IP**, the row shows a required **Static IP Address** field. The network object already defines the subnet, gateway, and DNS. The adapter supplies only its own address.

* Enter a bare IPv4 or IPv6 address without a prefix length (for example, `192.168.1.10`, not `192.168.1.10/24`).
* The address must fall within the network's subnet so the port has working connectivity.

### Static IP - Adapter Specific networks

When an adapter is bound to a network whose IP Address Config is **Static IP - Adapter Specific**, the network defines no IP details of its own. The adapter carries its own network configuration. The row shows two required fields inline:

* **Kind**: The IP addressing stack (**Dual-stack, IPv4 preferred**, **Dual-stack, IPv6 preferred**, **IPv4 Only**, or **IPv6 Only**). The value is pre-filled from the bound network.
* **Static IP Address**: The fixed address for this port, as a bare IPv4 or IPv6 address without a prefix length.

Select **Network settings** in the row to open a modal with the optional per-adapter settings:

| Field | Description |
| - | - |
| **Subnet** | The port's subnet in CIDR notation (for example, `192.168.1.0/24`). |
| **Gateway** | The default gateway address or hostname. |
| **Domain** | The DNS domain this port appends to unqualified names. |
| **DNS Servers** | One or more DNS server addresses, comma-separated. |
| **NTP Servers** | One or more NTP server addresses (IP or FQDN), comma-separated. |
| **MTU** | Maximum Transmission Unit in bytes, 1280 to 65535. Defaults to 1500 when left blank. |

All fields in the modal are optional. If an optional value fails validation, the row shows how many settings need attention until you correct them.

> [!NOTE]
>
> When you apply a static network to several selected adapter rows at once, the wizard expands each affected row so you can enter the required address for every adapter. Each adapter needs its own address; the bulk action does not copy IP values between rows.

To create a **Static IP - Adapter Specific** network ahead of onboarding, see [Create a Network](https://zededa.mintlify.site/new-ui/infrastructure-services/networks/create-a-network.md).

## Verify the Result

After creating the node:

* Return to **Infrastructure > Fleet > Nodes**.
* Confirm the node appears in the list.
* Confirm the node is assigned to the expected project.
* Open the node detail page and check status, admin state, and EVE-OS information.
* If the node is not online yet, confirm the device has booted EVE-OS and can reach Edge Infrastructure Services.

> [!NOTE]
>
> After onboarding, EVE-OS disables keyboard, VGA, and console access by default as a security measure. If you need physical local access to the node (for example, to use the Local UI or open a debug shell) re-enable these after onboarding by pushing the following configuration items from Edge Infrastructure Services:
>
> ```text theme={"dark"}
> zcli edge-node update NODE_NAME --config=debug.enable.usb:true
> zcli edge-node update NODE_NAME --config=debug.enable.vga:true
> zcli edge-node update NODE_NAME --config=debug.enable.console:true
> ```
>
> See [Manage Nodes with EVE-OS Local UI](https://zededa.mintlify.site/new-ui/infrastructure-services/manage-nodes-with-local-ui.md) for details.

> [!NOTE]
>
> Consider enabling last-resort SSH access while the node is connected and healthy. Last-resort SSH is an emergency break-glass method for reaching a node when EdgeView and standard SSH are both unavailable. Because it is enabled by pushing a config through Edge Infrastructure Services, it cannot be turned on after the node goes dark. Enable it proactively on production nodes, then disable it when it is no longer needed.
>
> ```text theme={"dark"}
> zcli edge-node update NODE_NAME --config=debug.enable.ssh.last.resort:true
> ```
>
> See [Enable Last Resort](https://zededa.mintlify.site/new-ui/infrastructure-services/troubleshooting/enable-last-resort.md) for the full procedure.

## Next Steps

* Review [Node status and health](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/node-status-and-health.md).
* Open [Node details](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/node-details.md).
* Configure [node adapters](https://zededa.mintlify.site/new-ui/infrastructure-services/nodes/configure-node-adapters.md) before deploying Applications that need specific network behavior.