Configure Edge Synchronization

This guide will help you set up and use Edge Sync.

Edge Sync (formerly “Local Operator Console”) is an HTTP server that stands in for ZEDEDA Cloud as a controller when your edge nodes don’t have Internet access, and thus don’t have access to ZEDEDA Cloud. In doing so, Edge Sync enables you to ensure continuity of service during planned and unplanned outages, to run your edge nodes primarily on an air-gapped network, or to more efficiently transition your nodes to the cloud from an air-gapped network.

Rather than completely replacing ZEDEDA Cloud, however, Edge Sync focuses on managing edge node and edge application configurations. It also collects runtime metrics from your nodes and applications.

When you use Edge Sync, your edge nodes will still periodically try to connect to ZEDEDA Cloud as normal. When they can't, they’ll fall back to your edge sync server. When they can connect to ZEDEDA Cloud, they will always prioritize those configurations, thus avoiding conflicting configurations.

You can run Edge Sync on any machine as long as your edge nodes can access it over some local network, for example, LAN or WLAN.

Prerequisites and restrictions

• Your edge node must be running at least EVE-OS version 9.7.
• Your edge nodes must be onboarded to ZEDEDA Cloud before you can use them with Edge Sync. Edge Sync does not support onboarding edge nodes.
• You must have Docker running on the machine that will run Edge Sync.
• Edge Sync can't manage an edge node that it runs on.
• (Optional) Available with EVE-OS version 14.5.2-LTS or greater. If you intend to use collect-info.sh for troubleshooting, then you need a local HTTP Data Store within the air-gapped environment where you’re running Edge Sync.

Set up Edge Sync

The procedures in this section will help you set up your Edge Sync server. After you’re all set up, you’ll be ready to use Edge Sync with its API.

Download Edge Sync

The Edge Sync image is hosted on Docker Hub. You either need to pull it onto your server directly, or you need to copy it onto your server.

Follow these steps to download Edge Sync.

1. Open your terminal.
2. Pull the Edge Sync image from Docker Hub.

   docker pull zededa/edge-sync

3. Verify that your machine has the Edge Sync image.

   docker images

4. Ensure that you see something similar to the following in the output of the previous command.

   zededa/edge-sync   latest     76a1607cab7d   1 month ago   6.19MB

Start Edge Sync

To start Edge Sync on your server, run the following Docker command in your server’s terminal.

Note that this command opens two listening ports: 1180 for the API and 8100 for the datastore.

docker run -p 1180:1180 -p 8100:8100 zededa/edge-sync

Enable Edge Sync on an Edge Node

Edge nodes will only fall back to Edge Sync if you have enabled the feature for the edge node. To do so, complete the following procedure for each edge node that should use Edge Sync.

1. Log in to ZEDEDA Cloud.
2. Click on Edge Nodes on the left side nav.
3. Click on the edge node that you want to enable.
4. Go to the node’s Basic Info tab.
5. Click the Edit icon.
6. Check the box labeled Edge Sync Configure.
   1. Enter the URL of your Edge Sync server in the following format:
      http://YOUR_EDGE_SYNC_IP_ADDRESS:1180
      • Replace YOUR_EDGE_SYNC_IP_ADDRESS with the IP address of your Edge Sync server. 
      • Note that the GUI will not give you an error if you're missing the http or the port.
   2. If you intend to use collect-info.sh for troubleshooting, select the Data Store that you configured in the prerequisites.
7. Click Save.

Download a configuration from ZEDEDA Cloud

Before you can send configurations to your Edge Sync server, you'll need to download them from ZEDEDA Cloud. The following procedure explains how to do so manually using the ZEDEDA GUI.

1. Log in to ZEDEDA Cloud.
2. Click on Edge Nodes on the left side nav.
3. Click on the edge node for which you want to download a configuration.
4. Click on the More Actions icon.
5. Click on Download Edge Sync Config.
6. Find the config file in your Downloads directory.

Download a bulk configuration from ZEDEDA Cloud

Before you can send bulk configurations to your Edge Sync server, you'll need to download them from ZEDEDA Cloud. The following procedure explains how to do so manually using the ZEDEDA GUI.

1. Log in to ZEDEDA Cloud.
2. Click on Edge Nodes on the left side nav.
3. Click the checkboxes of the edge nodes for which you want to download a configuration.
4. Click on the ellipsis (...) icon.
5. Click on Download Edge Sync Config.
6. Find the config file in your Downloads directory. The output is a single JSON file that aggregates multiple node configurations for each selected node into a file titled edge_sync_config_config_{timestamp}.json

Using the Edge Sync API

After you set up Edge Sync, you can manage and monitor your fleet of edge nodes using the following endpoints, which enable you to build custom integrations and applications to meet your needs.

In the following CURL request examples, replace $LOCURL with the local URL or IP address of your Edge Sync server. For example on a Linux host, you can do the following:

export LOCURL=http://YOUR_LOC_SERVER_IP_ADDRESS:1180

Upload configurations

POST: /config

Uploads a device config bundle. Each file in the bundle is a protobuf config response.

Syntax:

Substitute $LOCURL.

curl -F file=@filename.json http://$LOCURL/api/v1/user/config

Example assuming the file name downloaded as EDGE_SYNC_CONFIG_20250716145923.json:

curl -F file=@EDGE_SYNC_CONFIG_20250716145923.json http://172.16.0.111:1180/api/v1/user/config

Example of a config bundle that contains a single configuration:

{"EdgeSyncBlobList": [{"devId":"d8bf6b3a-917f-44dc-bdae-7542e7f7de88","config":"0adf4b0adc4b0a…..“}]}

You won't get a confirmation response after the upload, but you'll see log messages on your Edge Sync server:

time="2025-06-30T21:03:55Z" level=info msg="Config bundle uploaded successfully"

Get a list of online edge nodes

GET: /devs

Returns list of UUIDs of all online devices in JSON format. Devices are considered online if there is a recent ‘metrics’ update from an edge node.

Syntax:

Substitute $LOCURL.

curl http://$LOCURL/api/v1/user/devs

Example:

curl http://172.16.0.111:1180/api/v1/user/devs

Example response:

["123bab0f-a567-4fc2-98b1-c82c77cf75o8"]%

Get information for an edge node

GET: /id/$UUID/info

Returns a ZInfoMsg for the specified device in JSON format. If the device is not online, Edge Sync returns 404 Not Found.

Example:

Substitute $LOCURL and $UUID.

curl http://$LOCURL/api/v1/user/id/$UUID/info

Get metrics for an edge node

GET: /id/$UUID/metrics

Returns a ZInfoMsg for the specified device in JSON format. If the device is not online, Edge Sync returns404 Not Found.

Example:

Substitute $LOCURL and $UUID.

curl http://$LOCURL/api/v1/user/id/$UUID/metrics

Send a command to an edge node

POST: /id/$UUID/command/{shutdown|shutdown-poweroff}

Supported commands:

• shutdown: shuts all application down
• shutdown-poweroff: shuts all application down and powers the device off

Example:

Substitute $LOCURL and $UUID. Choose one command from {shutdown|shutdown-poweroff}.

curl -X POST http://$LOCURL/api/v1/user/id/$UUID/command/{shutdown|shutdown-poweroff}

Send a command to an edge application

POST: /id/$UUID/app/$APPUUID/command/{purge|restart}

curl -X POST http://$LOCURL/api/v1/user/id/$UUID/app/$APPUUID/command/{purge|restart}

Using the Edge Sync GUI

You can also use Edge Sync from the GUI of your Edge Sync Server. The documentation is available there, but it is static. So you can also refer to it here in the Help Center for the latest live updates. 

Prerequisites

• You already onboarded your edge nodes in ZEDEDA Cloud.
• You already configured the Edge Sync endpoint in the edge node’s Edge Sync Configuration section.
• You already configured a local Data Store. 

Download Cloud Configurations

Before you can send configurations to your Edge Sync server, you'll need to download them from ZEDEDA Cloud. 

Download one configuration

1. Log into ZEDEDA Cloud.
2. Click Edge Nodes on the left panel.
3. Click on the edge node where you want to download a configuration.
4. Click the ellipsis (...) icon.
5. Click Download Edge Sync Config.
6. Find the config file in your Downloads directory.

Download a bulk configuration

1. Log into ZEDEDA Cloud.
2. Click Edge Nodes on the left panel.
3. Check the checkboxes of the edge nodes where you want to download a configuration.
4. Click the ellipsis (...) icon.
5. Click Download Edge Sync Config.
6. Find the config file in your Downloads directory. The output is a single JSON file that aggregates multiple node configurations for each selected node into a file titled edge_sync_config_{timestamp}.json

Import Configurations

After you download a configuration from  ZEDEDA Cloud, you can import it to Edge Sync.

1. In your browser, enter the URL of your Edge Sync Server: http://YOUR_EDGE_SYNC_IP_ADDRESS:1180
2. Click the Edge Nodes tab.
3. Check the checkboxes of the edge nodes where you want to import a configuration.
4. Click the Import Configuration menu.
5. Drag and drop or select the file to upload.
6. Click the Import Configuration button. 

Apply Configurations

After you import a configuration, you can apply it to nodes that have configurations available for update.

1. In your browser, enter the URL of your Edge Sync Server: http://YOUR_EDGE_SYNC_IP_ADDRESS:1180
2. Click the Edge Nodes tab.
3. Click the Apply Configuration menu.
4. Check the checkboxes of the edge nodes where you want to import a configuration.
5. Click the Apply Configuration button.

Manage Edge Nodes

Management actions are only available if the edge node is not connected to ZEDEDA Cloud. 

1. In your browser, enter the URL of your Edge Sync Server: http://YOUR_EDGE_SYNC_IP_ADDRESS:1180
2. Click the Edge Nodes tab.
3. Check the checkboxes of the edge nodes that you want to manage.
4. Click the ellipsis (...) icon.
5. Use one of the following actions. 

Shutdown

You can shut down an edge node when you need to gracefully shut down the applications running on the edge node.

1. Click the checkboxes next to one or more edge nodes that you want to shut.
2. Click the ellipsis (...) icon.
3. Select Shutdown from the drop-down.
4. Confirm the action.

Power off 

You can power off an edge node when you need to gracefully shut down the applications running on EVE-OS and also power off the edge node.

5. Click the checkboxes next to one or more edge nodes that you want to power off.
6. Click the ellipsis (...) icon.
7. Select Power Off from the drop-down.
8. Confirm the action.

Edge app instances that are halted due to this command will resume their previous state after the edge node is powered back on.

Reboot

You can reboot the active edge node to apply changes or recover from issues. 

1. Click the checkboxes next to one or more edge nodes that you want to reboot.
2. Click the ellipsis (...).
3. Select Reboot from the drop-down.
4. Confirm the action.

Rebooting the edge node must show Admin Status as 'Active,' and the Run state will eventually become 'Online.'

Collect info

The Collect Info option (based on collect-info.sh) can be used to collect all info from an edge node, which helps to debug and resolve EVE-OS issues. 

You can set up the HTTP(s) datastore and, as part of the edge sync configuration, you can configure the datastore to use for pushing collect-info tar files. Then you can trigger the action to capture the collect info and this will push the collect-info.tgz file to the configure datastore.

1. Click the checkboxes next to one or more edge nodes that you want to reboot.
2. Click the ellipsis (...).
3. Select Collect Info from the drop-down.
4. Confirm the action.

Manage Edge App Instances

Management actions are only available if the edge node is not connected to ZEDEDA Cloud. 

1. Log into Edge Sync.
2. Click the Edge Apps tab.
3. Check the checkboxes of the edge apps that you want to manage.
4. Click the ellipsis (...) icon.
5. Use one of the following actions. 

Restart 

You can restart an edge app instance. 

1. Click the checkboxes next to one or more edge app instances that you want to restart.
2. Click the ellipsis (...).
3. Select Restart from the drop-down.
4. Confirm the action.

Purge

You can return to the initial state whenever you want to start fresh in the same instance. 

1. Click the checkboxes next to one or more edge app instances that you want to purge.
2. Click the ellipsis (...).
3. Select Purge from the drop-down.
4. Confirm the action.

Upgrade 

There are some things to consider about upgrading applications while airgapped or disconnected. When configuring an app image in ZEDEDA Cloud, more than one Data Store can be selected as the source. Edge Sync uses the first Data Store as the primary, and the other two as secondaries.

The general recommendation is to configure the primary as the cloud/online Data Store for use-cases where the edge node will be temporarily disconnected (hybrid deployments) and the secondary as a local datastore which will be used as a fallback in case the primary is not reachable. These secondary datastores (HTTP Servers or Docker Registries) must be accessible on the local network, similar to the Edge Sync API endpoint.

In the case of completely airgapped environments, configuring only a single/local datastore would suffice.

Currently the Application Instance upgrade workflow, implies the following steps:

1. In ZEDEDA Cloud, you first upgrade the application template.
2. Select all the affected application instances and trigger the “Purge & Update” action. ZEDEDA Cloud will update the Application Instances Manifest in the device config.
3. Select all the devices from the list and download the corresponding Edge Sync configuration file.
4. Import the Edge Sync configuration file in the Edge Sync UI
5. Select the nodes in the Edge Sync UI where the configuration must be applied.