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

# CPU Placement for Application Instances

> Set a topology-aware CPU placement policy on an edge app and override it per application instance to control CPU pools, SMT threads, and NUMA locality.

## Introduction

CPU placement controls how the vCPUs of an application map to the physical CPUs of the node. It replaces the former on/off **CPU Pinning** toggle with a topology-aware policy. You choose a CPU pool, how many SMT threads each reserved core runs, and whether the CPUs must fit on one NUMA node.

Use CPU placement for latency-sensitive workloads such as real-time data processing, industrial control systems, and AI inference pipelines, where consistent CPU performance matters more than sharing cores with other applications.

You set CPU placement in two places:

* On the **edge app definition**, as the **Default for new instances**.
* On each **application instance**, where you can keep the app definition settings or override them. The instance policy always takes precedence over the app definition.

### 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).
* The app type is **Virtual Machine** or **Container**. Docker Compose apps do not support CPU placement. Module apps keep the legacy **Enable CPU Pinning** tile on the **Drives** step.
* To use a pool other than **Housekeeping**, the target node must report the CPU placement capability. This requires EVE-OS (Edge Virtualization Engine) with CPU placement support on KVM and a CPU topology that EVE-OS can read.
* To use the **Isolated** pool, the node must be booted with isolated CPUs (`isolcpus`).

## Placement settings

### CPU pool

| Pool | Description |
| - | - |
| **Housekeeping** | Shares the node's housekeeping CPUs with other workloads. No dedicated cores and no isolation. CPU pinning is disabled. |
| **Dedicated** | Reserves CPUs for this workload, with CPU pinning and SMT- and NUMA-aware placement. Provides no kernel isolation or real-time latency guarantees. |
| **Isolated** | Adds kernel-level isolation to dedicated placement, on whole physical cores. Requires a node booted with isolated CPUs. If the node reports no isolated CPUs, the option shows as **Isolated (no isolated CPUs)** and cannot be selected. |

Selecting **Dedicated** or **Isolated** turns on CPU pinning. Selecting **Housekeeping** turns it off.

### Core allocation

When the pool is **Dedicated** or **Isolated**, select how vCPUs map to physical cores:

| Option | Description |
| - | - |
| **Dedicated logical CPUs** | Reserves one logical CPU per vCPU. Other workloads may use SMT siblings on the same physical core. Not available for the **Isolated** pool. |
| **One thread per core** | Reserves one physical core per vCPU. Its other SMT thread stays unused. |
| **Both SMT threads per core** | Uses both threads of each reserved physical core, with two vCPUs per core. Requires a node with SMT and an even vCPU count. |

### Advanced placement settings

Expand **Advanced placement settings** to tune whole-core placement. Select **Use throughput preset** to apply the recommended settings for dedicated physical cores.

| Setting | Options |
| - | - |
| **Memory locality** | **Ignore NUMA** allows CPUs to span NUMA nodes. **Prefer one NUMA node** spans nodes only if the cores do not fit on one. **Require one NUMA node** requires all CPUs to fit on one NUMA node, and the application does not start if they cannot fit. |
| **Disk and device emulation** | **On housekeeping cores** keeps disk and device emulation off your dedicated cores. **On my dedicated cores** runs emulation on your dedicated cores, sharing CPU time with the application. Not shown for **Reduced Isolation** containers. |

For **Reduced Isolation** (native) containers, the **CPU pinning** row and **Disk and device emulation** setting are hidden because there is no enclosing VM.

## Set the default on an edge app

CPU placement is part of the **Sizing** section of the edge app creation wizard. The step is named **Resources & CPU** for Virtual Machine apps and **Features & Sizing** for Container apps.

1. In the sidebar, select **My Library**.
2. Select the **Edge Apps** filter tab.
3. Select the **Create Edge App** floating action button.
4. Select **Virtual Machine** or **Container** as the app type.
5. Complete the **Identity** step and click **Next**.
6. Under **Sizing**, set **vCPUs**.
7. In the **CPU placement** panel, labeled **Default for new instances**, select a **CPU pool**.
8. If you selected **Dedicated** or **Isolated**, select a **Core allocation** and, optionally, expand **Advanced placement settings**.
9. Complete the remaining steps. The **Review** step shows a summary of the CPU placement policy. Click **Create**.

The policy applies to new instances of the app. Existing instances keep their CPU settings.

## Edit the default on an existing edge app

You can change the CPU placement policy after an edge app is created.

1. In the sidebar, select **My Library** and open the edge app.
2. Click the **Configure** (gear) icon.
3. In the left navigation, select **Hardware > Resources**.
4. Change the settings in the **CPU placement** panel.
5. Click **Save Changes**.

Edge apps created with the former **CPU Pinning** toggle show **Legacy CPU pinning** or **Legacy shared CPUs**. The existing behavior is preserved until you change these settings. To return a changed policy to the legacy setting, expand **Restore CPU settings** and select **Use legacy CPU pinning**.

## Override the policy on an application instance

When you [deploy an application instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-instance.md), the **Deployment Target** step shows a **CPU placement** panel after you select the edge app.

1. Select one of the following:
   * **Use app definition settings** to deploy with the edge app's default policy.
   * **Override for this application** to set a different policy for this instance only.
2. If you override, change the **CPU pool**, **Core allocation**, and advanced settings. The vCPU count comes from the app definition and cannot be changed here.
3. Review the per-node check below the panel. Each selected node shows **CPU placement supported** or the reason the policy cannot run on it, plus its last reported free capacity. Reported capacity is not a reservation.

To discard the override, click **Reset to app definition**. An override applies only to this instance. The app definition stays unchanged.

## View the policy and placement status

The application instance [detail page](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/app-instance-details.md) shows:

* A **CPU placement** card on the **Details** tab with the instance policy: **CPU pool**, **CPU pinning**, **vCPUs**, **Profile**, **Assigned CPUs** reported by the node, and **Memory locality**. Expand **CPU policy details** for core allocation, SMT threads per core, and disk and device emulation.
* A placement status pill in the header when the node reports a placement condition. See [CPU placement status](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/app-instance-details.md#cpu-placement-status).

If the hosting node does not place CPUs, the card shows `This node does not place CPUs; the saved CPU placement policy is not enforced on it.`

## Considerations

* **Core availability**: **Dedicated** and **Isolated** reserve CPUs exclusively. If the node does not have enough free cores for the vCPU count, the instance waits for CPUs or cannot be placed. Check the per-node capacity in the deployment wizard before you deploy.
* **Even vCPU counts**: **Both SMT threads per core** requires an even vCPU count. Change the vCPU count or select **One thread per core**.
* **Nodes without SMT**: On a node with no SMT siblings, select **One thread per core** or **Dedicated logical CPUs**.
* **Repacking**: When CPUs become fragmented, an instance can show **Needs repack**. A repack runs on the node and restarts every app on that node that needs repacking, not just this one.

## Next Steps

> [card] [Deploy an Application Instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-instance.md)
>
> Deploy the edge app as a running instance on a node.

> [card] [My Library](https://zededa.mintlify.site/new-ui/marketplace/my-library.md)
>
> View and manage all edge app definitions in your enterprise library.