HowTo: SSH into host device




This is just a quick guide on gaining SSH access to a host device with your openBalena setup. I can confirm that this works with both development and production balenaOS images, but for production images you must make sure that your SSH key is included in the config.json of the device’ boot partition. More information on that can be found here.

You are going to need a system tool called proxytunnel to do this, and I have only tested this on an Ubuntu system personally. I am assured that the process will work on macOS too, but how you get proxytunnel installed is outside the scope of this post.

$ sudo apt install proxytunnel
$ proxytunnel -V
proxytunnel 1.9.0 (rev 242) Copyright 2001-2008 Proxytunnel Project

Then you should use the balena CLI tool to create an API key for your account:

$ balena api-key generate proxytunnel

Registered api key 'proxytunnel':


This key will not be shown again, so please save it now.

This key will be required, so make a note of it. Now it’s time to configure SSH to use proxytunnel to connect to the balena VPN tunnelling service on your openBalena instance:

$ nano ~/.ssh/config

Host *.balena
  ProxyCommand proxytunnel -p vpn.<your openBalena domain>:3128 -d %h:22222 -F ~/.ssh/balena-ssh
  ServerAliveInterval 30

Substitute the domain as appropriate. Now create the permissions file:

$ nano ~/.ssh/balena-ssh


Make sure the permissions on this file are acceptable:

$ chmod 600 ~/.ssh/balena-ssh

You are ready to go, to connect you will need the full UUID of the device, and you should use it like so:

$ ssh root@<full UUID>.balena

This will ask you to confirm the host identification and then drop you into a root prompt. If you’re on a production image, then the SSH keys on your machine will be used to identify you, so they must be setup on the device first, otherwise you will see a rejection due to not having a valid key.

Error SSH to device via balena-cli
SSH Connection From Server
SSH: Could not resolve hostname
pinned #6


Hi @richbayliss
Thanks for this guide. Very helpful!

Just one quick question. When SSH is fixed/completed in balena-cli will devices deployed with SSH using this method then be SSH-able via balena-cli or will further updates-changes to end devices be required?



Hey, I am glad you found it useful!

I cannot say for certain that devices will not need changes to work with the balena-cli implementation, but the way this method is making the connection is dependant on the HTTP CONNECT proxy implementation in the VPN service container, and I am not aware of any plans to change that service.