Search by Tags

First Steps with Secure Offline Updates


Article updated at 22 Jun 2022
Compare with Revision


Warning: This feature is a work in progress. The release date is estimated at the end of Q2 2022.

The Secure Offline Updates is a feature soon to be released in Torizon. It is an alternative for the already available Torizon Remote Updates, using the same technology stack: OSTree and Aktualizr. Offline Updates brings the capability to perform secure application and OS updates to TorizonCore based devices that may not be able to update remotely. For example, devices that rarely, or never, connect to the internet or devices with limited bandwidth.

You can learn more about updates with Torizon on our overview article, and for more in depth knowledge, read theTorizon Remote Updates Technical Overview .

Main Features

With the Offline Updates feature it is possible to:

  • Execute full-stack, secure and reliable updates on devices without an internet connection
  • Automatically trigger the update on a device with an update medium - USB, SD Card, or network volumes.
  • Perform synchronous updates - both the OS and the Application as a single component
  • Automatically rollback to the last working version of the OS or the application in case the update fails
  • Block updates from happening from the application’s side, in case you have a critical application that cannot stop for an update to take place
  • Create a single Lockbox for multiple devices with different hardware


Many of the names and technologies used in Remote Updates are also used in Offline Updates. However, this feature requires some new unique terminology:


Lockbox is central to using Offline Updates. In this context, the Lockbox is the object that will contain all the required files that will be deployed to the updating device, along with the metadata necessary to make it a secure operation.

First Steps


In order to perform offline updates, you should have:

The Update Process

The update processes of a device with Offline Updates and Remote Updates are similar since both are based on the same technology stack. You can see the workflow in the diagram below:

  • Offline Update Workflow

    Offline Update Workflow

Creating the Packages

The first step is to bring your OS Image/Application to the Torizon Platform Services domain. To create an Application Package you should push a docker-compose file to the Torizon Platform Services with TorizonCore Builder. Note that you have to perform two actions before pushing it to Torizon Platform:

  1. Use the --canonicalize argument to generate a canonical version of the docker-compose file.
  2. Rename the canonical docker-compose file to '<your-docker-compose>.lock.yaml'.

Remember that you will also have to push your application to a docker registry, so TorizonCore Builder can download it when building the Lockbox.

To create a Torizon OS Package, you should use TorizonCore Builder to push images built by you or other collaborators. Remember, you can always use Toradex's provided images out-of-the-box.

Defining the Lockbox

The next step is to define the Lockbox in the Torizon Platform Web UI. The Lockbox itself will contain all of the files required for the update. It will also contain the necessary metadata to make it an easy, secure, and reliable process.

To define a Lockbox you have to:

  1. Select the desired OS and/or application packages
  2. Give it a name, so you can refer to it in future steps

Note: You can define a single Lockbox for updating devices with different hardware since they are capable of validating and selecting the correct OS package.

Creating the Lockbox

With the Lockbox defined, the next step is to create the actual Lockbox and load it into an update medium. This is a physical drive that holds the Lockbox, like an SD card or a USB drive. To create the Lockbox and load it into an update medium, you have to:

  1. Use TorizonCore Builder to download all the files and create the Lockbox previously defined on Torizon Platform Services
  2. Load the Lockbox folder generated by TorizonCore Builder into a physical drive

Deploying the Offline Update

Now that you have the update medium, it becomes a matter of physically going to the device and deploying the update:

  1. Insert the update medium (loaded with the Lockbox) into the device
  2. Wait for the update to finish
  3. Remove the update medium. At this point, the device is updated

Note: The update process is fully automated and no user intervention is required at any time. If you are performing an OS or synchronous update, the board will automatically reboot once.


Toradex has presented webinars about Secure Offline and Online Updates and you can watch them on demand.

Secure Offline and Online Updates for Linux Devices

Learn more about this webinar on the landing page, or watch it below: