Skip to main content
Version: 6

First Steps with Secure Offline Updates


Secure Offline Updates is a newly-released feature 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 have an internet connection, have limited bandwidth, have no network connection at all, or are permanently on an airgapped network.

You can learn more about updates with Torizon on our overview article, and for more in depth knowledge, read the Torizon 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, we introduce some new terminology to talk about offline updates and how they are secured:


The Lockbox is the main thing to understand when using Offline Updates. When you deliver an update using Torizon Remote Updates, it's a bit like sending an electronic funds transfer: you use the Torizon Platform to order the device to update to a particular software version, and then we take care of the rest, using secured communications channels (mTLS) and signed metadata that ensures the device can validate the software and installation instructions it recieves. For offline updates, there's no direct communication between the platform and the device, so we need an alternate mechanism to provide the same security guarantees: that's what we call the Lockbox.

A Lockbox is a collection of binary files, installation instructions, and software repository metadata. You can put it on a USB stick and carry it to a device, and the device will have everything it needs to make sure that the contents of that lockbox haven't been tampered with. Lockboxes are implemented using Uptane PURE-2, designed for securing updates of safety-critical automotive software.

First Steps


In order to perform your first steps with offline updates, you should satisfy all of the following pre requisites:

  • Device running a TorizonCore image without containers or with a previous version of your application containers
  • Commercial license for your Torizon Platform Services account
  • Device provisioned on the same account
  • Device configured for using offline update
  • The file download from your Torizon Plattform account section
  • The TorizonCore OS images and/or application files for the updates readily available
  • TorizonCore Builder installed on your host machine

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

Uploading software packages to Torizon Platform

The first step is to upload your OS Image and/or Application to the Torizon Platform. To create an Application Package you should push a docker-compose file to the Torizon Platform Services with TorizonCore Builder.


To be compatible with Secure Offline Updates, it must be canonicalized, which can be done using the --canonicalize argument.

If a name for the package is explicitly specified with --package-name, then it should also end with .lock.yml or .lock.yaml. Moreover, due to some known limitations, the package name must only employ basic ASCII characters excluding control ones and those in the set \/:*?" ><|, otherwise the Lockbox generation may fail later.

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.


If you want to deploy simultaneously the OS and application with Torizon Platform Services, you should use the synchronous update feature of our Torizon Platform, instead of customizing your image to bundle containers to a TorizonCore image, since its bundled containers are not capable of being deployed without Toradex Easy Installer.

Defining the Lockbox

The next step is to define the Lockbox in the Torizon Platform Web UI. This is the step where you decide exactly what software will go into the lockbox, so that the Torizon Platform can generate signed install instructions allowing your devices to trust the update.

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

Creating the Lockbox

Once the lockbock has been defined, you are ready to use TorizonCore Builder to download the files, metadata, and signatures that the device uses for validation. Use TorizonCore Builder for this step, and all the required files will be downloaded onto your workstation.

You can then copy the files onto a storage medium of your choice.

Deploying the Offline Update

Now that you have the update medium, you can take it to the device and deploy 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

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.


Your device must be configured for offline updates for this to work. You'll need to follow the detailed instructions on configuration, to make sure the path to the storage medium's mount location is correct.


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:

Send Feedback!