Mason Docs

Build and deploy your 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. In part 3, you learned the basic definitions of a Mason OS configuration.

This guide will walk you through registering and building a Mason OS configuration on the Mason Platform, and deploying that configuration to a device group.

When any project configuration is deployed to a Mason device, your device will perform a Factory data reset . See our guide for factory resets to learn more


For this example, we are using an example group named testgroup-c210 and example project named iheartlives-c210


  1. Make sure all media and APKs referenced in your Mason OS configuration are registered with the Mason OS platform already by visiting

    For more information about registering media and artifacts, visit our Mason CLI documentation

    $ mason register media bootanimation iheartlives-distro-boot 1 ~/code/iheartlives-distro/
    ------------ Boot animation ------------
    File path:
    Name: iheartlives-distro-boot
    Version: 1
    Continue registration? [Y/n]: y
    100%|███████████████████| 3.16M/3.16M [00:08<00:00, 379kB/s]
    Boot animation 'iheartlives-distro-boot' registered.
    $ mason register apk com.iheartlives.distribution.apk
    ------------ App ------------
    File path: com.iheartlives.distribution.apk
    Package name: Test App
    Version name: 1.0.12
    Version code: 12
    Continue registration? [Y/n]: y
    100%|███████████████████| 7.51M/7.51M [00:11<00:00, 656kB/s]
    App 'Test App' registered.
  2. Using the Mason CLI, register your Mason OS configuration using the command mason register config

    Visit our documentation on registing Mason OS configurations

    $ mason register config ~/code/iheartlives-distro/iheartlives-c210.yml
    ------------ OS Config ------------
    File path: iheartlives-c210.yml
    Name: iheartlives-c210
    Version: 4
      - 'com.iheartlives.distribution.apk' at version 4
    Boot animation: 'iheartlives-distro-boot' at version 4
    Continue registration? [Y/n]: y
    100%|███████████████████| 925/925 [00:00<00:00, 8.74kB/s]
    OS Config 'iheartlives-c210' registered.
    Build queued for OS Config 'iheartlives-c210'.
    You can see the status of your build at
  3. After you register a config, you should see the project build appear on the Project page. If the build fails, you should see an error message. Otherwise, when the build succeeds, it's ready to deploy to a device group!

    Controller builds for iheartlives-c210

  4. Using the Mason CLI, push your built project to a device group

    Visit our documentation on pushing Mason OS builds to groups

    $ mason deploy config iheartlives-c210 4 testgroup-c210
    ------------ Deployment ------------
    Name: iheartlives-c210
    Type: config
    Version: 4
    Group: testgroup-c210
    Push: False
    Continue deployment? [Y/n]: y
    Config 'iheartlives-c210' deployed.
  5. After the project is pushed to your device group, you will see the successful deployment listed on the Deployments section of the Group page

    Controller deployments for iheartlives-c210

  6. (Optionally) Move Mason devices in and out of this group to see them update with the Mason OS configuration you've specified!

    View our guide for moving devices between groups


Next steps