Skip to content
Balena Supervisor: balena's agent on devices.
Branch: master
Clone or download
Latest commit 558424e Apr 26, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github codeowners: Add @CameronDiver, @pcarranzav and @Page- Mar 8, 2019
.versionbot v9.14.6 Apr 25, 2019
automation Parallelise cache pulling for builds Mar 28, 2019
src fix: Run db log cleanup on init - after migrations Apr 25, 2019
test misc: Fix spurious test errors Apr 25, 2019
tools/dind dindctl: Allow mounting a backup.tgz to test migration backups Dec 12, 2018
typings types: Upgrade dockerode types, and remove fixes which are superceded Apr 8, 2019
.dockerignore Switch to using knex migrations to set up the database, and change th… Mar 6, 2018
.editorconfig Add mocha to enable unit testing Apr 4, 2018
.gitattributes Add a .gitattributes file to make sure files for use on linux have li… Oct 13, 2015
.gitignore dindctl: Allow mounting a backup.tgz to test migration backups Dec 12, 2018
.gitmodules Use resinos-in-container for the development dind supervisor Apr 20, 2018
.lintstagedrc Update to resin-lint 2 and add a precommit hook for prettier Nov 2, 2018
.resinci.yml Add a .resinci.yml to disable regular docker and npm builds Nov 2, 2018 v9.14.6 Apr 25, 2019
Dockerfile misc: Update build stages to debian stretch Mar 27, 2019 Add license and reorganize README headings Oct 27, 2015
Makefile dindctl: Allow mounting a backup.tgz to test migration backups Dec 12, 2018 Rename most of the documentation and variable names from resin to balena Nov 2, 2018
avahi-daemon.conf network: Add MDNS support for `.local` domains Aug 23, 2018
dindctl dindctl: Allow mounting a backup.tgz to test migration backups Dec 12, 2018 avahi: Remove default service definitions Apr 5, 2019
fix-jsonstream.js Use a custom webpack loader to avoid uncaught exceptions from JSONStream Oct 31, 2017
hardcode-migrations.js Fix webpack loader for knex migrations so it works with knex 0.15.2 Dec 12, 2018
knexfile.js Fix migrations directory path in knexfile for local development Mar 21, 2018
package-lock.json v9.14.6 Apr 25, 2019
package.json v9.14.6 Apr 25, 2019 Quick fix: use quotes in bash comparison Oct 13, 2015
sync.js Use webpack watching for sync.js for a faster dev cycle Dec 20, 2018
webpack.config.js Use webpack watching for sync.js for a faster dev cycle Dec 20, 2018

balena-supervisor Tickets in Progress

Join our online chat at Gitter chat

This is balena's supervisor, a program that runs on IoT devices and has the task of running user Apps (which are Docker containers), and updating them as the balena API informs it to.

The supervisor is a Node.js program.

Running a supervisor locally

This process will allow you to run a development instance of the supervisor on your local computer. It is not recommended for production scenarios, but allows someone developing on the supervisor to test changes quickly. The supervisor is run inside a resinOS instance running in a container, so effectively it's a Docker-in-Docker instance (or more precisely, balenaEngine-in-Docker).

Set up config.json

To configure the supervisor, you'll need a tools/dind/config.json file. There's two options on how to get this file:

  • Log in to the balenaCloud dashboard, create or select an application, click "Add device" and on the Advanced section select "Download configuration file only". Make sure you use an x86 or amd64 device type for your application, for example Intel NUC.
  • Install the balena CLI with npm install -g balena-cli, then login with balena login and finally run balena config generate --app <appName> -o config.json (choose the default settings whenever prompted).

The config.json file should look something like this:

(Please note we've added comments to the JSON for better explanation - the actual file should be valid json without such comments)

	"applicationId": "2167", /* Id of the app this supervisor will run */
	"apiKey": "supersecretapikey", /* The API key to provision the device on the balena API */
	"userId": "141", /* User ID for the user who owns the app */
	"username": "gh_pcarranzav", /* User name for the user who owns the app */
	"deviceType": "intel-nuc", /* The device type corresponding to the test application */
	"apiEndpoint": "", /* Endpoint for the balena API */
	"deltaEndpoint": "", /* Endpoint for the delta server to download Docker binary diffs */
	"vpnEndpoint": "", /* Endpoint for the balena VPN server */
	"listenPort": 48484, /* Listen port for the supervisor API */
	"mixpanelToken": "aaaaaaaaaaaaaaaaaaaaaaaaaa", /* Mixpanel token to report events */

Additionally, the uuid, registered_at and deviceId fields will be added by the supervisor upon registration with the balena API. Other fields may be present (the format has evolved over time and will likely continue to do so) but they are not used by the supervisor.

Start the supervisor instance

Ensure your kernel supports aufs (in Ubuntu, install linux-image-extra-$(uname -r)) and the aufs module is loaded (if necessary, run sudo modprobe aufs).

./dindctl run --image balena/amd64-supervisor:master

This will setup a Docker-in-Docker instance with an image that runs the supervisor image. You can replace :master for a specific tag (see the tags in Dockerhub) to run a supervisor from a branch or specific version. The script will pull the image if it is not already available in your local Docker instance.

If you want to develop and test your changes, you can run:

./dindctl run --image balena/amd64-supervisor:master --mount-dist

Note: Using --mount-dist requires a Node.js 6.x installed on your computer.

This will mount the ./dist folder into the supervisor container and build the code before starting the instance, so that any changes you make can be added to the running supervisor with:

./dindctl refresh

Testing with preloaded apps

To test preloaded apps, run balena preload (see the balena CLI docs on an OS image for the app you are testing with. Then copy the apps.json file from the resin-data partition into tools/dind/apps.json.

This file has a format equivalent to the local part of the target state endpoint on the balena API.

Make sure the config.json file doesn't have uuid, registered_at or deviceId populated from a previous run.

Then run the supervisor like this:

./dindctl run --image balena/amd64-supervisor:master --preload

This will make the Docker-in-Docker instance pull the image specified in apps.json before running the supervisor, simulating a preloaded balenaOS image.

View the supervisor's logs

./dindctl logs

This will show the output of journalctl inside the Docker-in-Docker container. You can pass additional options, for instance, to see the logs from the supervisor service:

./dindctl logs -fn 100 -u resin-supervisor

Stop the supervisor

./dindctl stop

This will stop the container and remove it, also removing its volumes.

Developing with a balenaOS device

If you want to test local changes (only changes to the Node.js code are supported) on a real balenaOS device, provision a development OS image and power up the device. On the balenaCloud dashboard, take note of the device's IP address. Then run:

./sync.js <device IP>

This will build the supervisor code and sync it onto the running supervisor container inside the device, and then restart it.

Build a local supervisor image

This should rarely be needed as --mount-dist allows you to test any changes to the Node.js code without a full rebuild. However, if you've changed code in the base image or the Dockerfile you will need to build the proper supervisor Docker image.

Build the supervisor with a specific tag, and for a specific architecture, like this:

./dindctl build --tag master --arch amd64

This will build the supervisor Docker image locally. If you then run docker images you should see the repo/tag you set there. Keep in mind several images will be pulled for caching purposes.

Base image

The supervisor uses the resin-supervisor-base as a base image. This is a minimal Linux image containing busybox, rsync and Node.js, and it's built with the Yocto project.


You can run some unit tests with:

npm test

You'll need Node.js 6 installed, and having run npm install first. The supervisor runs on Node 6.13.1, so using that specific version will ensure tests run in the same environment as production.


If you're interested in contributing, that's awesome!

Here's a few guidelines to make the process easier for everyone involved.

  • Every PR should have an associated issue, and the PR's opening comment should say "Fixes #issue" or "Closes #issue".
  • We use Versionist to manage versioning (and in particular, semantic versioning) and generate the changelog for this project.
  • At least one commit in a PR should have a Change-Type: type footer, where type can be patch, minor or major. The subject of this commit will be added to the changelog.
  • Commits should be squashed as much as makes sense.
  • Commits should be signed-off (git commit -s)


Copyright 2015 Rulemotion Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

You can’t perform that action at this time.