> ## 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. # Manage Application Instances > Use ZCLI commands to deploy, view, start, stop, restart, update, purge, snapshot, and delete application instances from the command line. Use the ZEDEDA CLI (ZCLI) to manage application instances from the command line. This article covers `zcli edge-app-instance` commands for deploying an instance of an edge app to an edge node or node cluster, viewing instances, controlling their lifecycle, updating their configuration, attaching patch envelopes, working with snapshots, and deleting instances, with syntax and examples for each operation. An application instance is a deployed copy of an edge app running on a specific edge node. The edge app definition (image, resources, and interfaces) is managed separately with `zcli edge-app`. The same `zcli edge-app-instance` commands apply to virtual machine, container, and Docker Compose application instances. For background on compose instances, see [Docker Compose Overview](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/docker-compose.md). ## Before You Start * ZCLI is installed and authenticated against your enterprise. See [Get Started](https://zededa.mintlify.site/zcli-reference/get-started.md). * 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 edge app you want to deploy exists (list edge apps with `zcli edge-app show`), and the target edge node is onboarded (list nodes with `zcli edge-node show`). * For GUI-based application instance management, see [Applications Overview](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/applications-overview.md), [Deploy an Application Instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-instance.md), [Manage an Application Instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/manage-an-application-instance.md), and [Application Instance Status and Health](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/app-instance-status-and-health.md). ## Deploy Application Instances ### Create an application instance Create an application instance record from an edge app and deploy it to a single edge node (`--edge-node`) or to an edge node cluster (`--edge-node-cluster`). When you deploy to a cluster, you can optionally pin the instance to one node in the cluster with `--enable-app-pinning=true` together with `--designated-node-id`. This is the ZCLI equivalent of the **Deploy** flow in the console. Each `--network-instance` and `--adapter` value maps an interface name defined in the edge app to a resource on the node. The interface name must match an interface in the edge app definition, or ZCLI rejects the command with `Interface not found in edge app template`. ```text theme={"dark"} zcli edge-app-instance create --edge-app= (--edge-node= | (--edge-node-cluster= [(--enable-app-pinning= --designated-node-id=)])) [--title=] [--description=<description>] [--start-delay=<delay>] [--tags=<key:value>...] [--local-profile-server-override=<val>] [--network-instance=<network-instance>...] [--network-tag=<key:value>...] [--adapter=<name>...] [--adapter-tag=<key:value>...] [--custom-configuration=<cloud-config>] [--api-version=<api-version>] ``` | Flag | Description | | - | - | | `--edge-app=<edge-app-name>` | Edge app to deploy. List edge apps with `zcli edge-app show`. | | `--edge-node=<edge-node>` | Edge node to deploy to. List nodes with `zcli edge-node show`. | | `--edge-node-cluster=<edge-node-cluster>` | Edge node cluster to deploy to. List clusters with `zcli edge-node-cluster show`. | | `--enable-app-pinning=<true\|false>` | Pin the instance to one node in the cluster. Default is `false`. Use with `--designated-node-id`. | | `--designated-node-id=<designated-node-id>` | ID of the cluster node to pin the instance to. | | `--network-instance=<network-instance>` | Bind an app interface to a virtual network, in the form `<interface>:<virtual-network>`. You can append a static IP address, MAC address, or access VLAN ID. See [Interface binding formats](#interface-binding-formats). Repeat for each interface. | | `--network-tag=<key:value>` | Bind an app interface to a virtual network by tag, in the form `<interface>:<tag-key>:<tag-value>`. You can append an access VLAN ID. See [Interface binding formats](#interface-binding-formats). Repeat for each interface. | | `--adapter=<name>` | Bind an app interface to a physical adapter, in the form `<interface>:<adapter>`. Repeat for each adapter. | | `--adapter-tag=<key:value>` | Bind an app interface to an adapter by tag, in the form `<interface>:<tag-key>:<tag-value>`. Repeat for each adapter. See the note that follows this table before you use this flag. | | `--start-delay=<delay>` | Seconds to wait before starting the instance after the edge node reboots or restarts. | | `--custom-configuration=<cloud-config>` | Path to a JSON file with custom configuration (cloud-init variable groups) for the instance. | | `--local-profile-server-override=<val>` | Local profile server key to override. Accepts comma-separated values. | | `--tags=<key:value>` | User-defined name/value pairs, for example `--tags=SENSOR_NET:humidity`. Repeat for multiple tags. | > [!NOTE] > > In the current version of ZCLI, `--adapter-tag` does not work reliably on `create` or `update`. If you pass `--adapter-tag` without `--adapter`, ZCLI stops with a Python error (`UnboundLocalError`) and does not create or update the instance. If you pass it together with `--adapter`, ZCLI looks up the interface position of the first adapter tag from the preceding `--adapter` value, so the tag can be assigned to the wrong interface position. Until this is fixed, bind adapters by name with `--adapter`. #### Interface binding formats A `--network-instance` value starts with the interface name and the virtual network name, separated by a colon. You can append more colon-separated values after the virtual network name. ZCLI identifies each value by its content. | Appended value | How ZCLI recognizes it | Example | | - | - | - | | Static IPv4 address | The value contains a period. | `10.1.0.20` | | MAC address | The value contains a hyphen and no period. Write the MAC address with hyphens, not colons, because ZCLI splits the value at each colon. | `00-16-3E-12-34-56` | | Access VLAN ID | The value contains only digits. | `100` | ZCLI ignores appended values that match none of these patterns, without an error. Because the value is split at each colon, you cannot set an IPv6 address this way. Example (bind `eth0` to a virtual network with a static IP address, a MAC address, and access VLAN 100): ```text theme={"dark"} zcli edge-app-instance create MY_APP_INSTANCE --edge-app=MY_EDGE_APP --edge-node=MY_NODE --network-instance=eth0:MY_NET:10.1.0.20:00-16-3E-12-34-56:100 ``` A `--network-tag` value takes the form `<interface>:<tag-key>:<tag-value>`, or `<interface>:<tag-key>:<tag-value>:<vlan-id>` to also set an access VLAN ID. ZCLI ignores a `--network-tag` value with more than three colons, without an error. Example (bind `eth0` by tag and set access VLAN 100): ```text theme={"dark"} zcli edge-app-instance create MY_APP_INSTANCE --edge-app=MY_EDGE_APP --edge-node=MY_NODE --network-tag=eth0:MGMT_NET:test-uplink:100 ``` #### Examples Example (deploy to a single node with the edge app defaults): ```text theme={"dark"} zcli edge-app-instance create MY_APP_INSTANCE --edge-app=MY_EDGE_APP --edge-node=MY_NODE ``` Example (bind interface `eth0` to a virtual network and interface `usb0` to a physical adapter): ```text theme={"dark"} zcli edge-app-instance create MY_APP_INSTANCE --edge-app=MY_EDGE_APP --edge-node=MY_NODE --network-instance=eth0:MY_NET --adapter=usb0:usb0 ``` Example (bind an interface to a virtual network by tag instead of by name): ```text theme={"dark"} zcli edge-app-instance create MY_APP_INSTANCE --edge-app=MY_EDGE_APP --edge-node=MY_NODE --network-tag=eth0:MGMT_NET:test-uplink ``` Example (deploy to a node cluster and pin the instance to one node): ```text theme={"dark"} zcli edge-app-instance create MY_APP_INSTANCE --edge-app=MY_EDGE_APP --edge-node-cluster=MY_CLUSTER --enable-app-pinning=true --designated-node-id=MY_NODE_ID ``` ## View Application Instances ### View application instances List all application instances in your enterprise, filter the list by project, edge app, edge node, cluster, state, name substring, or tag, or show one instance by name or UUID. Add `--detail` to a single-instance query to print the full configuration. Add `--summary` to a list query to print only the count summaries. Use `--page-size` to reduce the number of records returned per API call if a large list times out; it does not change the output. ```text theme={"dark"} zcli edge-app-instance show [--api-version=<api-version>] [[[<name> | --uuid=<uuid>] [--detail]] | [[--edge-app=<edge-app>] [--edge-node=<edge-node> | --edge-node-cluster=<edge-node-cluster>] [--summary] [--name-pattern=<name-pattern>] [--page-size=<page-size>] [--project=<project>] [--state=<state>] [--tags=<key:value>]]] ``` Example (all application instances): ```text theme={"dark"} zcli edge-app-instance show ``` Example response: ```text theme={"dark"} Edge App Instance Edge App Edge Node Admin State Run State MY_APP_INSTANCE MY_EDGE_APP MY_NODE Active Unknown Total: 198 App Instance Summary: Error : 4 Init : 0 Online : 20 Other : 3 Suspect : 103 Unknown : 68 Total: 198 App instance summary count by app type: APP_TYPE_CONTAINER : 121 APP_TYPE_DOCKER_COMPOSE : 3 APP_TYPE_MODULE : 0 APP_TYPE_UNSPECIFIED : 0 APP_TYPE_VM : 74 APP_TYPE_VM_RUNTIME : 0 Other : 0 ``` Example (filter by project, state, and name substring): ```text theme={"dark"} zcli edge-app-instance show --project=MY_PROJECT --state=Activated --name-pattern=ubuntu ``` Example (all instances on one edge node): ```text theme={"dark"} zcli edge-app-instance show --edge-node=MY_NODE ``` Example (one application instance): ```text theme={"dark"} zcli edge-app-instance show MY_APP_INSTANCE ``` Example response: ```text theme={"dark"} Edge app Instance Name: MY_APP_INSTANCE Edge app Instance Title: MY_APP_INSTANCE Tags: Edge App Name: MY_EDGE_APP Edge Node: MY_NODE Admin State: Active Run State: Unknown CPUs: 1 Memory: 524288 Created at: Fri May 02 2025 09:58:20 PM Last Config update: Fri May 02 2025 09:58:20 PM ``` Example (full configuration of one application instance): ```text theme={"dark"} zcli edge-app-instance show MY_APP_INSTANCE --detail ``` For the meaning of the admin and run states in the output, see [Application Instance Status and Health](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/app-instance-status-and-health.md). ## Control Application Instances The following commands change the running state of an application instance on its edge node without changing its configuration. Each one corresponds to an action in the console **Actions** menu on the instance detail page. ### Start an application instance Start an application instance that is halted or that was created but not activated. Existing volumes and network connections are preserved. This is the ZCLI equivalent of the console **Start** action. ```text theme={"dark"} zcli edge-app-instance start <name> [--api-version=<api-version>] ``` Example: ```text theme={"dark"} zcli edge-app-instance start MY_APP_INSTANCE ``` ### Stop an application instance Stop an application instance on its edge node. Stopping halts the entire instance, not just its containers, and the application is unavailable until you start it again. Persistent volumes are preserved. This is the ZCLI equivalent of the console **Stop** action. ```text theme={"dark"} zcli edge-app-instance stop <name> [--api-version=<api-version>] ``` Example: ```text theme={"dark"} zcli edge-app-instance stop MY_APP_INSTANCE ``` ### Restart an application instance Stop and restart an application instance. Expect a brief outage while the instance restarts. This is the ZCLI equivalent of the console **Restart** action. ```text theme={"dark"} zcli edge-app-instance restart <name> [--api-version=<api-version>] ``` Example: ```text theme={"dark"} zcli edge-app-instance restart MY_APP_INSTANCE ``` ### Refresh or purge an application instance Refresh an application instance to update it to the latest version of its edge app. A refresh restarts the instance but keeps its data. This is the ZCLI equivalent of the console **Update** action. Add `--purge` to clear all local application data and redeploy from the latest edge app version. A purge is destructive: the instance returns to its initial state and all local data is lost. This is the ZCLI equivalent of the console **Purge & Update** action. If snapshots are enabled for the instance, consider creating a snapshot first so you have a rollback point. See [Snapshots](#snapshots). ```text theme={"dark"} zcli edge-app-instance refresh <name> [--purge] [--api-version=<api-version>] ``` Example (refresh, data is kept): ```text theme={"dark"} zcli edge-app-instance refresh MY_APP_INSTANCE ``` Example (refresh and purge, data is lost): ```text theme={"dark"} zcli edge-app-instance refresh MY_APP_INSTANCE --purge ``` ## Update Application Instances ### Update an application instance Update the title, description, tags, start delay, local profile server override, or interface bindings of an existing application instance. ZCLI retrieves the current record, applies the values you pass, and writes the modified record back. Flags you omit keep their current values. This is the ZCLI equivalent of the console **Configure** (gear) action. ```text theme={"dark"} zcli edge-app-instance update <name> [--title=<title>] [--description=<description>] [--tags=<key:value>...] [--local-profile-server-override=<val>] [--start-delay=<delay>] [--network-instance=<network-instance>...] [--network-tag=<key:value>...] [--adapter=<name>...] [--adapter-tag=<key:value>...] [--api-version=<api-version>] ``` Example (change the description): ```text theme={"dark"} zcli edge-app-instance update MY_APP_INSTANCE --description=MY_NEW_DESCRIPTION ``` Example (set a staggered start delay and add a tag): ```text theme={"dark"} zcli edge-app-instance update MY_APP_INSTANCE --start-delay=60 --tags=SENSOR_NET:humidity ``` ## Manage Patch Envelopes A patch envelope delivers runtime bundle artifacts to a running application instance without redeploying it. The same patch envelope can be attached to several instances in one command. All instances named in one command must belong to the project you pass with `--project`. Patch envelopes are not available for Docker Compose application instances. For how to create patch envelopes, see [Update Applications with Runtime Bundles](https://zededa.mintlify.site/new-ui/infrastructure-services/build-and-library/update-applications-with-runtime-bundles.md). ### Attach a patch envelope Attach a patch envelope to one or more application instances. Repeat `--app-instance` for each instance. This is the ZCLI equivalent of the console **Attach Patch Envelope** action. ```text theme={"dark"} zcli edge-app-instance patch-envelope-attach --app-instance=<name>... --project=<project> --patch-envelope=<patch-envelope> ``` Example: ```text theme={"dark"} zcli edge-app-instance patch-envelope-attach --app-instance=MY_APP_INSTANCE --project=MY_PROJECT --patch-envelope=MY_PATCH_ENVELOPE ``` ### Detach a patch envelope Detach the currently attached patch envelope from one or more application instances. Files previously delivered by the envelope are no longer available to the application. This is the ZCLI equivalent of the console **Detach Patch Envelope** action. ```text theme={"dark"} zcli edge-app-instance patch-envelope-detach --app-instance=<name>... --project=<project> ``` Example: ```text theme={"dark"} zcli edge-app-instance patch-envelope-detach --app-instance=MY_APP_INSTANCE --project=MY_PROJECT ``` ## Snapshots A snapshot captures the current state of an application instance, including its configuration and attached volumes, so you can roll back to that state. Snapshots are useful for instances on edge nodes that are air-gapped or offline for long periods. Snapshots must be enabled for the instance, and only one snapshot is retained per instance; creating a new snapshot replaces the existing one. Snapshots are not available for Docker Compose application instances. For an overview, see [Application Snapshot Overview](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/application-snapshots.md). ### Create a snapshot Create a snapshot of an application instance. This is the ZCLI equivalent of the console **Create Snapshot** action. Without `-f`, ZCLI first checks that the hosting edge node supports immediate snapshots and, if it does not, stops with the message `The related device doesn't support immediate snapshots`. With `-f`, ZCLI skips this check and submits the request anyway. ```text theme={"dark"} zcli edge-app-instance snapshot-create --app-instance=<name> [-f] ``` Example: ```text theme={"dark"} zcli edge-app-instance snapshot-create --app-instance=MY_APP_INSTANCE ``` ### View snapshots List the snapshots of an application instance, or show one snapshot by name. Use the list output to find the snapshot name for the activate and delete commands. ```text theme={"dark"} zcli edge-app-instance snapshot-show [<snapshot-name>] --app-instance=<name> ``` Example (all snapshots of one application instance): ```text theme={"dark"} zcli edge-app-instance snapshot-show --app-instance=MY_APP_INSTANCE ``` Example response: ```text theme={"dark"} Edge App Snapshot Edge App Instance State Activate Immediate ----------------------- ----------------- ------- -------- --------- SNAPSHOT-20250502221806 MY_APP_INSTANCE INVALID False False ``` Example (one snapshot): ```text theme={"dark"} zcli edge-app-instance snapshot-show SNAPSHOT-20250502221806 --app-instance=MY_APP_INSTANCE ``` ### Activate a snapshot Roll the application instance back to the state captured in a snapshot. This is the ZCLI equivalent of the console **Rollback** action on the **Storage** tab of the instance detail page. ```text theme={"dark"} zcli edge-app-instance snapshot-activate <snapshot-name> --app-instance=<name> ``` Example: ```text theme={"dark"} zcli edge-app-instance snapshot-activate SNAPSHOT-20250502221806 --app-instance=MY_APP_INSTANCE ``` ### Delete a snapshot Delete a snapshot of an application instance. This is the ZCLI equivalent of the console **Delete** action for a snapshot on the **Storage** tab. ```text theme={"dark"} zcli edge-app-instance snapshot-delete <snapshot-name> --app-instance=<name> ``` Example: ```text theme={"dark"} zcli edge-app-instance snapshot-delete SNAPSHOT-20250502221806 --app-instance=MY_APP_INSTANCE ``` ## Delete Application Instances ### Delete an application instance Delete an application instance from its edge node. This action is irreversible. Without `-f`, ZCLI prompts you to confirm the deletion. This is the ZCLI equivalent of the console **Delete** action. ```text theme={"dark"} zcli edge-app-instance delete <name> [--api-version=<api-version>] [-f] ``` Example: ```text theme={"dark"} zcli edge-app-instance delete MY_APP_INSTANCE -f ``` ## Next Steps > [card] [Applications Overview](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/applications-overview.md) > > How edge apps, images, and application instances fit together. > [card] [Deploy an Application Instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-instance.md) > > Deploy an instance using the Edge Infrastructure Services console. > [card] [Manage an Application Instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/manage-an-application-instance.md) > > GUI-based lifecycle actions, snapshots, and patch envelopes. > [card] [Overview](https://zededa.mintlify.site/zcli-reference/overview.md) > > All ZCLI command procedures, organized by resource type.