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.


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.

Hi @richbayliss,

Are there any updates concerning this issue? As far as I know it doesn’t work out of the box yet, correct?

Thanks in advance!


Thanks for this - am just getting going with open-balena and this gets me into the host OS ok.

I guess I’m right then in using “balena logs” and “balena attach” to see what’s happening in the main container. Seems to work anyway.



No updates, the balena ssh mechanism is not compatible with openBalena deployments and we are working on that, but for now the only route is to tunnel the port 22222 as detailed.

Okay! Looking forward to that, but for now I’m going to explore the tunnel option as you’ve explained. Thanks for this!

I’m receiving this error while trying to SSH into my balenaOS devices, either into the host or the container:

[root@midgard open-balena]# balena ssh c94176664572c5654c6d9694f3dc219e
Connecting to: c94176664572c5654c6d9694f3dc219e
bash: enter: command not found
Connection to closed.

Edit: @richbayliss, can you just confirm that right now openBalena users can not SSH into both host devices or the containers on them? I quote:

No updates, the balena ssh mechanism is not compatible with openBalena deployments and we are working on that, but for now the only route is to tunnel the port 22222 as detailed.

I get to this topic while searching for a solution into the forum, so I’m not asking for a solution or an update, but I just hope this post can help people receiving the “bash: enter: command not found” error.

Also, maybe, the fact “balena ssh” is not working right now has to be mentioned under the “What’s the difference between openBalena and balenaCloud?” FAQ on

@daghemo you cannot use the balena ssh command with openBalena as it relies on a service which the openBalena stack doesn’t ship with. However, SSH is possible using either the method above OR using the balena tunnel command, like so:

balena tunnel {uuid} -p 22222:22222

This creates a listening socket on port 22222 of your localhost which you can then use any SSH client to connect to:

ssh root@localhost -p 22222

I hope this helps :+1:

1 Like

This mechanism is working well for me under Linux. What’s the best way to achieve the same with Windows? Will Putty do it?

Thanks, Alex

@ajlennon putty should work but worst case you can build yourself a little virtual machine or even docker container with SSH installed.