Improve this doc

SSH access

To help you debug and develop your applications, we've provided a browser based terminal and a command line tool for easy SSH access to your devices. With these tools, you have console access to any of your running containers, as well as to the host OS, letting you test out small snippets of code and check system logs on your device.

Note: Host OS SSH access is available for devices running balenaOS version 2.7.5 and above.

Using the dashboard web terminal

To use this feature, navigate to your application and select the device you want to access. You will see a Terminal window below the Logs window:

In order to start a terminal session for a service, you first need to ensure that your device is online and that the service container is running. If the container code crashes or ends quickly, it is not possible to attach a console to it. Check out our Dockerfile and Docker Compose guides for more information on keeping your containers running.

If your device is online, select a target and click the blue >_ Start Terminal session button. A terminal session should be initiated for you in a second or two. If you would like a bigger window for the terminal, you can click the Expand button in the upper-right corner.

Note: To copy and paste in the terminal window, you cannot use the normal Ctrl + C and Ctrl + V shortcuts. You can either select Copy and Paste from a menu, or use Ctrl + Insert for copy and Shift + Insert for Paste. For MacOS users, ⌘ + C and ⌘ + V work as expected.

Using balena ssh from the CLI

If you prefer to work from the command line, you can use balena ssh to connect to your application containers and the host OS. First, you will need to install the balena Command Line Interface (CLI). Once that is set up, run the following in your development machine's terminal:

$ balena ssh <device-uuid>

<device-uuid> is the unique identifier for the device you want to access, which can be found on the dashboard.

To access the host OS, add the --host or -s option:

$ balena ssh <device-uuid> -s

Note: Host OS access via the CLI requires CLI version 6.12.0 or above

balena ssh makes use of the balena VPN connection to access a device. This allows you to access and test devices wherever they are. If you want to SSH only on the internal network, you can install an SSH server in your container, as we show in the balena-openssh project.

One note is that if you run your own SSH in the container you won't automatically get your environment variables in the SSH session. To bring them in, simply run . <(xargs -0 bash -c 'printf \"export %q\n\" \"\$@\"' -- < /proc/1/environ). Now any operations or code you run from the SSH session will be able to access the environment variables you set on your balena dashboard (see gitter discussion for more info). Alternatively, use the following command in a Dockerfile to update the root's .profile so balena variables are sourced at each tty/ssh login:

echo ". <(xargs -0 bash -c 'printf \"export %q\n\" \"\$@\"' -- < /proc/1/environ)" >> /root/.profile

Troubleshooting with host OS access

Warning: Making changes to running services and network configurations carries the risk of losing access to your device. Before making changes to the host OS of a remote device, it is best to test locally. Changes made to the host OS will not be maintained when the OS is updated, and some changes could break the updating process. When in doubt, reach out to us for guidance.

Host OS SSH access gives you a handful of tools that can help you gather more information about potential issues on your device. Here are some tips for troubleshooting common issues:

Check logs


Information from a variety of services can be found using the journalctl utility. As the number of journalctl messages can be quite large, it is good to know how to narrow your search.

To find messages from a specific service, use the -u flag:

journalctl -u systemd-timesyncd

To return the last x messages, use -fn x:

journalctl -fn 100 -u balena-supervisor


For displaying messages from the kernel, you can use dmesg. Similar to journalctl, dmesg may have an unmanageable output without some additional commands:

dmesg | tail -n 100

Monitor balenaEngine

BalenaOS, beginning with version 2.9.0, includes the lightweight container engine balenaEngine to manage Docker containers. If you think the supervisor or application container may be having problems, you’ll want to use balena for debugging.

This command will show the status of all containers:

balena ps -a

You can also check the journalctl logs for messages related to balena:

journalctl -fn 100 -u balenaEngine

For devices with balenaOS versions earlier than 2.9.0, you can replace balena in these commands with docker.

Inspect network settings


NetworkManager includes a CLI that can be useful for debugging your ethernet and WiFi connections. The nmcli command, on its own, will show all interfaces and the connections they have. nmcli c provides a connection summary, showing all known connection files with the connected ones highlighted. nmcli d displays all network interfaces (devices).

Another useful place to look for NetworkManager information is in the journalctl logs:

journalctl -fn 100 -u NetworkManager


Similar to NetworkManager, ModemManager includes a CLI, mmcli, to manage cellular connections. mmcli -L provides a list of available modems.

Look up version information

Knowing what version of a specific service is being run on your device can help you troubleshoot compatibility issues, known bugs, and supported features.

Many services provide a direct option for displaying their version:

udevadm --version
systemd --version
openssl version

Understand the file system

In some cases, you may need to examine the contents of certain directories or files directly. One location that is useful for troubleshooting purposes is the /data directory, which contains your device's Docker images, persistent application data, and host OS update logs. The /boot directory includes configuration files, such as config.txt and NetworkManager connections.

Note that the filesystem layout may look slightly different from what you’d expect—for example the two locations mentioned above are found at /mnt/data and /mnt/boot, respectively.