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

# Deploy an Application Instance

> Create and deploy an edge application instance to a node or cluster from the Applications area of Edge Infrastructure Services.

## Introduction

Deploying an application instance is the process of selecting an edge app image from the Build section and running it on a specific node or cluster. The wizard collects basic details, the deployment target, the interface set and its network mappings, and custom configuration values before submitting the instance to the node. After Edge Infrastructure Services deploys it, the application instance starts, and EVE-OS (Edge Virtualization Engine) manages it on the node.

This article covers deploying to one node or one cluster. To deploy the same application to several nodes in a single tracked job, see [Deploy an Application to Multiple Nodes](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-to-multiple-nodes.md).

### Prerequisites

* 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).
* At least one edge app image exists in the Build section.
* At least one node is onboarded, online, and assigned to a project.
* The node has at least one network instance configured if the app image declares network interfaces.

## Open the Application Instance Creation Wizard

1. In the sidebar, navigate to **Infrastructure > Workloads > Applications**.
2. Select the contextual **+** create action.

The application instance creation wizard opens.

## Complete the General Step

In the **General** step, enter the basic details for this instance.

1. In the **Name** field, enter a unique identifier for this instance. Use alphanumeric characters and hyphens only (for example, `my-app-prod`). This field is required.
2. In the **Title** field, enter a human-readable display name. This field is required.
3. In the **Description** field, enter an optional description.
4. In the **Tags** field, add optional key-value pairs to classify this instance. Tags can be used to match deployments and automate policy assignments. See [Tagging](https://zededa.mintlify.site/new-ui/start/tagging.md).
5. Click **Next**.

## Complete the Deployment Target Step

In the **Deployment Target** step, select where to run the application and which app to deploy.

1. In the **Cluster/Nodes** dropdown, select the node or cluster to deploy to. This field is required. Selecting two or more nodes switches the wizard to the multi-node path described in [Deploy an Application to Multiple Nodes](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-to-multiple-nodes.md). If you select a cluster:
   * Optionally, select a **Pinned Node** to designate a preferred node within the cluster. Leave blank to let the cluster schedule the instance on any available node.
   * If you selected a pinned node, use the **Allow Failover** toggle to control failover behavior:
     * Off (default): the instance is strictly pinned to the selected node and will not run elsewhere.
     * On: the selected node is the preferred placement, but the instance can fail over to another cluster node if the preferred node goes offline.
   * If you select a two-node HA cluster, the wizard does not offer a **Pinned Node**. It shows **Placement is managed by the cluster** instead. While the cluster has two members, the controller runs the instance on the non-seed node. After a quorum reset leaves one member, the instance runs on that surviving node. Two-node HA uses preferred affinity so that the instance can fail over.
2. In the **Edge App** dropdown, search for and select the edge app image you want to deploy. This field is required.

The wizard automatically detects any persistent volumes required by the app image and shows their status as it verifies availability on the selected node.

For Virtual Machine and Container apps, a **CPU placement** panel appears after you select the edge app. Select **Use app definition settings** to deploy with the edge app's default policy, or **Override for this application** to choose a different **CPU pool**, **Core allocation**, and **Advanced placement settings** for this instance only. The vCPU count comes from the edge app and cannot be changed here. Below the panel, each selected node shows **CPU placement supported** or the reason it cannot run the policy, such as a node that does not report the CPU placement capability. Click **Reset to app definition** to discard an override. See [CPU Placement for Application Instances](https://zededa.mintlify.site/new-ui/marketplace/cpu-placement.md).

To adjust advanced runtime settings, expand the **Additional Configuration** section:

* **Start Delay**: the number of seconds to wait before the application starts. Enter `0` for immediate start.
* **Disable vTPM**: removes the virtual Trusted Platform Module from the VM for this instance. Enable this only when the guest OS is incompatible with vTPM. Not applicable for Docker Compose app types.
* **VMM Overhead**: overrides the default memory reserved for the hypervisor. Enter the value in MB when the VMM needs additional memory headroom on the target node. Not applicable for Docker Compose app types.
* **Persistence Storage Size**: shown only when the selected edge app is a VM with the Compose Runtime deployment type. Sets the size of the persistent data volume that stores the runtime's container state. The value is prefilled from the app and can be overridden per instance. Size it to match the app's VM drive size (for example, 10 GB). The volume's data survives upgrades of the runtime software.
* **Enable Logs**: allows this application instance to send logs to Edge Infrastructure Services. Enabled by default.

3. Click **Next**.

## Adjust the App Interfaces

The **App Interfaces** step appears only when all of the following are true:

* The edge app is a VM or container app. Docker Compose, module, and other app kinds do not have an editable interface set.
* The node hosting the instance runs EVE-OS (Edge Virtualization Engine) 17.3.0 LTS or greater, which supports an interface set that differs from the edge app's definition. On earlier versions, the instance deploys with the interfaces the edge app declares.
* The project the instance belongs to has **Interface Ordering** enabled. See [Interface Ordering for Application Instances](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/app-instance-interface-ordering.md).

If any condition is not met, the wizard omits this step and the instance deploys with the interfaces the app image declares.

This step is pre-filled from the edge app's own interfaces. Changes you make here apply to this deployment only and leave the application itself unchanged. You bind each interface to a network on the next step.

Each interface appears as a collapsible card showing its name, its kind (Virtual Network or Direct Attach), and whether it is Optional or Required. Click a card to expand it.

Whether an interface is Optional or Required is set by the edge app and cannot be changed in this step. Interfaces you add here are always Optional.

For each interface, you can set the following:

* **Name**: a unique identifier for the interface. Use up to 32 letters, numbers, dots, dashes, or underscores. Each name must be unique within the instance.
* **Kind**: select **Virtual Network** for an interface that attaches to a network instance, or **Direct Attach** for an interface that maps to an IO adapter on the node.
* **Inbound rules** and **Outbound rules**: access control rules for traffic on this interface. When a rule's action is **Limit**, set **Rate** (the sustained number of packets per minute the rule allows) and **Burst** (how many packets may pass back to back in a spike before the limiter throttles the flow down to the rate).

Interface numbers show the deployment order. To change the order, drag an interface card by its grip and drop it at the highlighted line, or click **Move up** or **Move down** on the card.

To add an interface, click **Add interface**. To remove an Optional interface, click the **X** on its card header. Required interfaces cannot be removed.

To discard every change made on this step and return to the application's own interface list, click **Reset to application**. This control appears only after the interface set differs from the application.

Removing every interface is allowed. An instance deployed with no interfaces has no network connectivity.

Click **Next**.

## Map Network Interfaces

In the **Network Interfaces** step, assign network connections to the interfaces carried over from the previous step.

If the instance has no interfaces to assign, a message confirms this and you can skip to the next step.

For each interface listed:

1. Click the interface row to expand it.
2. For a standard network interface, select a **Network Instance** from the dropdown. If no network instances are available on the selected node, use the inline quick-create option to create one.
3. For a direct-attach interface (IO adapter), select an **IO Adapter Bundle** from the dropdown. The available options are drawn from the adapters reported by the selected node.
4. For optional interfaces, use the **Enabled** toggle to include or exclude the interface from this deployment.
5. Required interfaces must be assigned before you can proceed.
6. Click **Next**.

## Set Custom Configuration Values (Optional)

The **Custom Config** step appears when the selected app image includes a custom configuration template.

Custom configuration variables allow you to provide environment-specific values without modifying the app image itself. For example, you might set a server URL or a feature flag that differs between production and staging deployments.

1. For each variable shown, enter the appropriate value. Required variables are marked with an asterisk.
2. Click **Next**.

## Review and Deploy

The **Review** step shows a complete summary: name, edge app, deployment target, CPU placement (labeled **From app definition** or **Instance override**), the interface set and its network assignments, and custom configuration values.

1. Review all sections. To make changes, click the relevant section heading or use the **Back** button.
2. When everything is correct, click **Create Application**.

Edge Infrastructure Services submits the request to create the application instance and confirms that it was submitted. The console then opens the App Instances list at **Infrastructure > Workloads > Applications > App Instances**. Creation is asynchronous: the node downloads the application image, runs the startup sequence, and reports status back to the platform.

### Track the Create Outcome

The console checks the create job in the background and reports the result in the background-tasks tray, the stack of cards in the corner of the console. The first check runs about 30 seconds after Edge Infrastructure Services accepts the request. The console then checks every 20 seconds, for up to 8 attempts.

When the result arrives, the card expands on its own and shows one of the following messages:

| Message | Link opens |
| - | - |
| **Cloud operation completed** | The detail page of the new application instance |
| **Cloud operation failed.** followed by the error detail | The detail page of the cloud job |

Click the link or the **X** to dismiss the card. You can drag the tray or minimize it while you keep working.

If the job is still running after the last check, the console marks the outcome as unresolved rather than failed. Check the job under **Infrastructure > Operations > Jobs** to see its final state.

## Verify the Deployment

After creating the application instance:

1. On the **App Instances** list, locate the new instance.
2. Wait for the background-tasks tray card to report **Cloud operation completed**. If it reports a failure, open the job from the card to review the error.
3. Confirm that the status column moves through the transitional states as the node processes the deployment. A typical sequence is **Provisioned**, **Downloading**, **Verifying**, **Init**, **Booting**, and then **Online**. For the full list of states, see [Application Instance Status and Health](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/app-instance-status-and-health.md).
4. Open the instance to view its detail page and confirm it is running on the expected node.

If the instance does not reach **Online** status after a reasonable time, navigate to **Infrastructure > Monitor > Logs**, filter by the instance, and review the log output for errors.

## Next Steps

> [card] [Manage an Application Instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/manage-an-application-instance.md)
>
> Take lifecycle actions, access the remote console, or attach a patch envelope.

> [card] [Deploy an Application to Multiple Nodes](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-to-multiple-nodes.md)
>
> Deploy the same application to many nodes in a single job.

> [card] [Monitor Logs](https://zededa.mintlify.site/new-ui/infrastructure-services/monitoring-logs-events-reports-jobs.md)
>
> Investigate startup issues or runtime errors.