Improve this doc
Get started with and

Get started with BeagleBone and Node.js


In this guide we will build a simple Node.js web server project on a BeagleBone. At its most basic, the process for deploying code to a BeagleBone consists of two major steps:

  • Setting up your BeagleBone with balenaOS, the host OS that manages communication with balena and runs the core device operations.
  • Pushing your Node.js project to the balena image builder, which pulls in all necessary dependencies and creates the container image for your application.

Once these steps are finished, your BeagleBone will download the container image, kick off your application, and begin sending logs to your balena dashboard!

What you will need

  • A Beaglebone Black or Beaglebone Green.
  • A 4GB or larger SD card. Both the Beaglebone Black and Green use a Micro SD card. The speed class of the card also matters - this determines its maximum transfer rate. We strongly recommend you get hold of a class 10 card or above.
  • An ethernet cable or WiFi adapter to connect your device to the internet. The WiFi adapter for the Beaglebone Black is known to be unstable at moment, it is recommended that you use a usb WiFi adapter with a large external antenna.
  • A mini USB cable the Beaglebone Black OR a micro USB cable for the Green.
  • [Optional] A 5VDC 1A power supply unit for the Beaglebone Black.
  • A balena account.

Note: Always run the board from 5VDC 1A minimum supply when using a WiFi Dongle. You may need to use a extension cable to move the dongle away from the planes of the PCB. We also have had instances where when placed in a metal case, there can be WiFi issues as well. It will also help to use a dongle with a real antenna on it.

Need help?

If you find yourself stuck or confused, help is just a click away:

  • The balenaCloud section of the forums is where our engineers address any issues you may be having with balena.
  • You can read more about our approach to support here.

Account setup

If you don't already have a balena account, make sure to sign up.

Adding an SSH Key

Balena uses git to push code from your computer to a dedicated repository. As part of the account creation process, you will be asked to add a public SSH key. The SSH key secures your connection to our server, letting us know you have the authority to make changes to the repository.

Note: You can click Skip to move past this step for now, but you will not be able to push code to your BeagleBone until you have added a public key to your account. This can be done at any time from the Preferences page on the dashboard.

If you have a public SSH key, simply paste it into the box provided and click Save Key:

You can also import your key from GitHub. If you choose this option, you will be asked to enter your GitHub username:

Don't have an SSH key?

If you are unfamiliar with SSH keys, we recommend you take a look at GitHub's excellent documentation. This will walk you through everything you need to create a key pair. Window's user? Be sure to check out these instructions.

Create an application

An application is a group of devices that share the same architecture and run the same code. When you provision a device, it is added to a specific application, but can be migrated to another application at any time.

To create an application, select the BeagleBone device type, select an application type, enter a name, and click Create new application:

Note: To create an application with multiple containers, you'll want to use the starter or microservices application type. The starter applications are full-featured and free for all users, with a limit of up to ten total devices across all starter applications.

This will take you to the dashboard for your newly created application, where you can manage your whole fleet of BeagleBones.

Add your first device

To connect with balena, your BeagleBone will need a balenaOS image that is configured for your device type, application, and network. Start by clicking Add device in your application dashboard:

For most applications, you will have the option to select a device type. By default, the device type you chose when you first created the application will be selected. Applications can, however, support any devices that share the same architecture, so you can choose another device type if needed.

After selecting a device type, you will see a list of available balenaOS versions. In general, the most recent version is recommended. You can also select whether you would prefer a Development or Production edition with the respective toggle:

Note: When you're first getting started, a Development image will be most useful, as it permits a number of testing and troubleshooting features. For production use, be sure to switch to a Production image. More details on the differences between Development and Production images can be found here.

A toggle is also used to select whether your network connection will be through Ethernet Only or with the option for WiFi + Ethernet. Selecting Wifi + Ethernet allows you to enter a WiFi SSID and WiFi Passphrase:

Clicking Advanced presents the option to select the rate at which your device checks for updates and the option to download just a configuration file (config.json) rather than an entire image:

Once you have finished your image configuration, click the Download balenaOS button. When the download completes, you should have a zipped image file with a name like, where FirstApp is the name you gave your application on the dashboard.

The next step is to flash the downloaded image onto your SD card using Etcher, a simple, cross platform SD card writer and validator. Once you have Etcher installed, start it up. To give Etcher access to your SD card, your system may prompt you to grant administrative privileges.

To create a bootable balenaOS SD card follow these steps:

  1. Click Select image and find your application's balenaOS image file.
  2. If you haven't already done so, insert your SD card into your computer. Etcher will automatically detect it. If you have more than one SD card inserted, you will need to select the appropriate one.
  3. Click the Flash! button.

Etcher will now prepare a bootable SD card and validate that it was flashed correctly. This can take roughly 3 or more minutes depending on the quality of your SD card. You'll get a little ping when it's done, and Etcher will safely eject the SD card for you.

Note: You can burn several SD cards with the same image file and all the devices will boot and provision into your application's fleet. You can also disable the auto-ejecting or validation steps from the Etcher settings panel.

Provision your device

Put the SD card into your device, and connect either the ethernet cable or WiFi adapter. Now hold down the small black button marked s2 (located near the SD card slot) and power up the device by inserting the power or USB cable.

You should only need to hold the button down for about 5 seconds until the blue LEDs start flashing like crazy. Basically, by holding down the button, we are telling the Beaglebone that we want to boot from the SD card instead of the onboard flash. From there, the OS which is on the SD card is flashed onto the internal eMMC memory.

Warning: This will completely overwrite any data on your devices' internal eMMC, so make sure to make a backup of any important data.

After a short while you should see your device pop up in the dashboard. It will appear in a configuring state as it flashes balenaOS to the internal media. This step can take a little time.

After the internal media has been flashed, your device will shut itself down. At this point you will see the device in a Post-Provisioning state and all its LEDs should be off. Before booting the device again, make sure to remove the SD card. You may then simply press the power button situated nearest to the ethernet port or pull out and replug the power cable.

Your device should now start booting from internal eMMC and in a minute or so you should have a happy Beaglebone device in the Idle state on your dashboard. From here on you can deploy code to your device with ease.

Note: If you have an HDMI screen attached (Beaglebone Black only), you should see "Booted - Check your balena dashboard." on the screen when the device boots. If instead you see rainbow colors or a blank screen, it could mean that the SD card was not burned correctly or is corrupted. Try burning the SD card again. If the issue persists, come and get help from our support team.

Deploy code

Now that we have a device or two connected to a balena application, let's deploy some code and actually start building something.

A nice first project to get your feet wet is a simple Express.js web server which will serve a static page on port :80. All the project source code can be found here on GitHub.

To clone the project, run the following command in a terminal or your preferred git client:

$ git clone

Note: This project runs an application in a single container. If you would like to start with a multicontainer project, run git clone

Once the repo is cloned, change directory into the newly created simple-server-node directory and add the balena git remote endpoint by running the command git remote add shown in the top-right corner of your application page:

$ cd simple-server-node
$ git remote add balena <USERNAME><USERNAME>/<APPNAME>.git

Note: On other git clients there may be an alternative way to add a remote repository.

So now we have set up a reference in our local git repository (the one on our development computer) to the balena application remote repository. So when we push new changes to this remote repository it will get compiled and built on our servers and deployed to every device in the application fleet.

Warning: The balena git repository is not intended as a code hosting solution, and we cannot guarantee the persistence of data in balena git remotes.

Now to deploy this code to all device(s) in the application just run the command:

$ git push balena master

If you want to completely replace the source code of the application with a new source tree, you may need to force the push by running git push balena master --force, due to how git works.

Note: On your very first push, git may ask you if you would like to add this host to your list of allowed hosts. If the ECDSA key fingerprint matches SHA256:NfwmqnKId5cx1RWpebbEuuM87bCJbdyhzRnqFES9Nnw, you are pushing to the right place. Type 'yes' to continue.

You'll know your code has been successfully compiled and built when our friendly unicorn mascot appears in your terminal:

This means your code is safely built and stored on our image registry. It should only take about 2 minutes to build your code and subsequent builds will be quicker because of build caching.

Your application will now be downloaded and executed by all the devices you have connected in your application fleet. You may have to wait about 6 minutes for the first push... So time for more tea, but don't worry, all subsequent pushes are much, much faster due to Docker layer sharing. You can see the progress of the device code updates on the device dashboard:

You should now have a node.js web server running on your device and see some logs on your dashboard. If you go to the Actions page for your device, you can enable a public URL, this URL is accessible from anywhere in the world.

If you follow the URL, you will be served a page with some additional balena learning resources and next steps. Alternatively, you can point your browser to your device's IP address.

Next steps

  • Learn more about the Dockerfile that is used to build your application.
  • Build an application that uses multiple containers.
  • Get to know the web terminal, which can be used to SSH into your application containers and the host OS.
  • Try out local mode, the most efficient way to rapidly develop and test your balena application.

Example projects

These example projects will give you an idea of more things that can be done with balena:

Basic Analog input in Node.js on the Beaglebone


A simple node.js project that uses the Octalbonescript library to read an analog voltage signal from P9_33 on the Beaglebone every 3 seconds.

Warning: --This project will only work on balenaOS images downloaded after 22-09-2015--

I2C proximity sensor


This is a simple node.js project that uses i2c-bus to get data from a VLNC4000 proximity & light sensor. It is made to be generic and act as base for any i2c sensor integration. It should work on any of the balena supported devices, you just need to make sure i2c is enabled in the kernel and know the i2c bus number for you device.

Enjoy Balenafying All the Things!