"Extract" BalenaOS with installed application


If I install BalenaOS on a device, and I deploy some Docker applications, is it possible to get an image of the OS with the installed application ? Like having a back-up image for instance.


Hello, would application preloading be useful to you? https://www.balena-staging.io/docs/reference/cli/#preload-image

It basically allows you to provision a device image with your application before you flash it. This preloaded image is basically identical to your device after pushing your app.

Yes, this could be a great solution!

However, I don’t understand how to use the preload command:

balena preload balena.img --app 1234 --commit e1f2592fc6ee949e68756d4f4a48e49bff8d72a0 --splash-image image.png

  • balena.img is the balena image I can download from the BalenaCloud dashboard?
  • If I have a Docker image locally on my PC, the hash in --commit <hash>is the hash of this Docker image I want to preload ?
  • What is the --app argument ? Is it the BalenaCloud application?


Hi Lucas, --app is used to specific the ID of the application being preloaded, and --commit refers to the commit hash of the specific application release you wish to preload. A more detailed explanation of the options is available via balena preload --help. Thanks.

Yes I read the documentation and --help but I don’t understand concretely what is --app or --commit.

  • In BalenaCloud dashboard, I can create Applications. Is --app the ID (name ?) of that Application ?

  • When I deploy services (Docker containers) on a BalenaOS devices, I can see in the BalenaCloud dashboard a Release hash. Is this hash the parameter to --commit ?


Hey @lpierrat

The --app argument should be followed by the ID (not the name) of your application - one place this is shown is in the browser address bar when you visit your application in the dashboard. It says https://dashboard.balena-cloud.com/apps/<app id>/devices; you can use this with the preload command.

You’re correct about the --commit argument, it’s the release hash of the release within that same application that you would like to preload. You can retrieve this by going to the list of releases within your application, clicking on the one you want and then copying the hash using the copy button that appears when you hover your mouse cursor over the ID on that page.

I hope this helps.

Yes, Thanks a lot!

Actually I’m still confused. Let’s restart from beginning :

On BalenaCloud, I create a new Application. I get the AppID .
From this application, I click Add device and I download the BalenaOS.img on my development machine.
On this development machine, I build my Docker application, and I get the hash of the built image.

Now I have all the information needed to preload the container into the img ?
balena preload BalenaOS.img --app AppID --commit hash

If so, what is the difference with doing balena push AppName when there is no device yet in the Application, and then when I add a new device the Docker container is automatically installed on this new device ?

Hey, these two flows should result in the same state. In the first case the application is preloaded into the image, meaning it does not have to be downloaded by a device that connects to the application. In the other case the device has to download the release as soon as it comes online. The main idea with preload is to remove this “dead time” between the moment the device is added and when the application is finally downloaded.

Thanks, clear.

I managed to test it, it works well with a release hash taken from the dashboard (that means that I have already run balena push for this application).

Is there a way to preload a docker image build locally on my PC ?

Let’s say I have my Dockerfile and I run docker build locally, then I get the hash from this build (= the image ID when I run docker images).
Is there a way to preload this docker image into the balenaOS.img ?


Hi Lucas,
Unfortunately there we do not yet provide a way to preload a locally built image. The preload features requires (for the time being) the app to be published to our registry.
Kind regards,

Ok thanks a lot!
Is it something planned in the future?

Hi Lucas, we have talked about this feature in the past but right now we don’t have any concrete plans to implement it anytime soon. Primarily because we don’t have enough resources to work on such a feature.

I’m adding your interest in this feature in our internal tracking system. We will post an update when we make progress on that front.

Ok, It was just to have an idea .
Thank you very much for your support

Hi again,

Once I burned the .img on the SD Card/USB Stick, I’m able to acces to the file system and for example add the configuration to connect behind a proxy.

Is there a way to do this configuration before burning the .img ?
So I could have a “ready to use” .img, easier to store in my cloud, for example.



We actually support connecting from behind a Proxy using redsocks. See this page on balena networking for using this feature.

Because it uses a file in the boot partition, you can actually add this file to the preloaded image before you flash an SD card/USB stick and provision a device. That way, all devices that use the image will both preload and register as well as use the Proxy for networking.

Hope this helps!

Best regards,


Sorry, I’ve just realised you’d added a link to the redsocks page, and I’d misunderstood the question! Yes, you don’t have to flash the SD card first, but if you have your preloaded image, you can mount it on your host OS and change the boot partition of the image itself to include the relevant Redsocks configuration file. In Windows and macOS, the very act of mounting the card will open the boot partition for you. In Linux, you’ll need to mount the first partition to do this.

Once the image has been modified, you can then flash the image to SD/USB and the device will immediately pick up and use the Proxy configuration.

Best regards,