Mason Docs

Create a custom Mason OS configuration

In part 1 of our 'Manage Projects' series, you were introduced to the concept of Mason OS configs and projects. In part 2, you learned how to create a Project on the Mason Platform.

This guide will walk you through the definition of a Mason OS configuration file, and walk you through the key attributes defined in a Mason OS configuration.

What is a Mason OS configuration?

Mason OS configuration files are defined using the YAML file format - .yml. You can create a Mason OS configuration using any text editor you like.

YAML files are easy to validate using linting and parsing techniques. For more information about YAML formatting, visit the YAML wiki page

Mason OS configuration specification

Mason OS configs can vary by device on the Mason Platform. To visit a Mason OS configuration specification, visit the documentation on our devices page, select the device you want, and then you can view the device's Configuration glossary from there.

Visit the Mason OS configuration glossary for our G450A1 device

Example Mason OS configuration

This is an example Mason OS configuration for a dedicated device used by a logistics company.

    name: warehouse-distribution
    version: latest
        disable_keyguard: true
        disable_status_bar: false
        config_allow_download_over_metered: false
        config_update_check_frequency: 6
        config_update_install_time: 12:30
        config_update_install_battery_threshold: 20
        config_update_prompt_prior_to_install: true
        config_allow_download_over_metered: true
        config_update_check_frequency: 12
        config_update_install_time: 01:00
        config_update_install_battery_threshold: 20

    - name: Test App
      package_name: com.warehouses.distribution
      version_code: 12

      name: warehouse-distro-boot
      version: latest

Configuration definitions

The following section of this guide will walk you through the definitions in the given example Mason OS configuration, shown above.


The os tag is the metadata declaration of the project config. Only two fields are required; name and version. The configuration section is where you define the exact behavior and details of the Mason OS specified by this file.

"os" name

This field should reference an existing project identifier in the Mason platform.

In this case, the project warehouse-distribution was created in step 2 of the "Manage Projects" series

"os" version

The os version is a numeric and monotonically incremented field that represents the "version" of a Mason OS config.

In all places where you must specify a version, the latest keyword can be used instead for a more hands-off approach to versioning, as the Mason Platform will increment Mason OS configuration versions for you.

Together, Mason OS name and version combinations must be unique. If you try to add a Mason OS config to the Mason Platform that includes a name and version combination that already exists in the Platform, the duplicate config will be rejected.

"os" configurations

The Mason OS configurations refer to a set of rules and attributes that, when built and deployed to a Mason device, will result in some specific behavior or state of the resulting Mason OS.

Mason OS configurations determine the expression of Mason OS on a Mason device. Think about the Mason OS configurations defined in this section as the electrical wiring and floorplan of a house. The Mason OS is the foundation and structural frame of the house, and the Mason Device is the finishing, roofing, and paint.

The Mason Platform provides Mason OS configurations that dictate everything and everything our customers need, from update policy, UI behavior, and even hardware behavior for a specific mason device.

Visit the Mason OS configuration glossary for our G450A1 device


The apps object enumerates all the registered Android applications that are to be included into the software build. Only the package_name and version_code properties are required.

  • The name attribute defines an arbitrary name (for your own record keeping)
  • The package_name attribute comes from the package name in your APK's AndroidManifest.xml
  • The version_code attribute comes from the version code in your APK's AndroidManifest.xml

For more details on registering an Android application to the Mason Platform, see our Mason CLI documentation for the command mason register apk


The media object enumerates all the media configurations for the software distribution.

Supported types are:

  • Boot animations
  • Splash screens

For more details on registering a boot animation to the Mason Platform, see our Mason CLI documentation for the command mason register media


Next steps