Skip to main content

SSH Tunnel add-on. Registering new pods with the admin web server

This add-on will use SSH to make your local Home Assistant setup available through a remote system. This add-on is only useful to those with access to a publicly available SSH server and some administrative privileges on that system.

Use SSH to make ports of your local Home Assistant setup available at or through a remote system. This forms yet another way to make the Lovelace UI and other services accessible from another network or the public internet. If you do not have the authority to open ports into your local network, and a VPN solutions seems overkill, this add-on might just be the solution for you.

The solution is only useful to those with access to a publicly available SSH server and some administrative privileges on that system.

SSH Tunnel Add-on is a well known tool to establish an SSH connection and keep it connected over hours and months. SSH is known for its high security and the ability to set up port forwarding in both directions through the SSH connection. In combination, this add-on offers tunneled port forwarding functionality.

The need of the SSH tunneling

It prevents us having to expose the POD on the internet.  The POD is only accessed via our AWS instance and the ssh tunnel from the POD to the AWS instance.  It allows us to remote access the POD's w/ a high level of security.

How a pod is registered and how it is assigned a port?

Pod info is stored in DynamoDB, the DB is scanned for the next available port and it's assigned to the POD.  We probably should store a "Next POD" or index the port number field so it's a more efficient lookup, but that won't be an issue until we get into more than a thousand or so pods.

What happens if a pod has the same name as an existing one?

Right now the port numbers are assigned in blocks of 10, starting at 10000, so pod 1 gets 10000-10009, and pod 2 gets 10010-100019, etc.  It uses 2 of them currently for ssh tunnel and http tunnel into the HASS instance.  There are 8 ports reserved for future services that we might need to tunnel from the AWS instance to the PODS.  When a number is assigned a lookup is done, in DynamoDB to validate that the port range is not in use by another pod.

How are the SSH keys handled? 

Right now ssh key provisioning is manual.  We have an open issue to add that functionality to the provisioning process.  It requires the generation of a private key on the POD and a public key to be handed off and stored on the AWS instance.  Part of the story for this is to figure out the design, off the top I say it will be an endpoint where the public key is POST'd that's authenticated by Cognito.  We'll want to use some validated parameter from Cognito to make sure the authenticated user is authorized to add a POD via the endpoint which brings me to the last part of this.

We need to write an authorizer lambda so that any endpoint we have will bounce off of the Cognito hosted UI and user the same usernames/passwords that we're currently using for the Wiki, etc.

We need to add the Cognito integration into Hass and test it.  That means someone can sign in once and they can get into the Wiki, The Admin UI (If Authorized), and the Home Assistant UI (If the authenticated user is authorized for that particular pod) with their Cognito Username and password, only having to log in once.


Set hostname and username, start once to generate a key pair, copy key pair over to remote server, start again, check log for success or error messages.


The installation of this add-on is pretty straightforward and not different in comparison to installing any other Home Assistant add-on.

After installation and first start, check the logs of the add-on to see further instructions and status details. The add-on creates an SSH keypair and uses it to connect to the given host. The public key can be found in the log after the first startup and must be copied to the destination server for this add-on to work. On your typical Linux system the public key is added to ~/.ssh/authorized_keys.

Remote Server Configuration

By default, forwarded ports can only be bound to localhost. To make it available on a public interface, either reconfigure SSH or set up a reverse proxy.


Option: seapod _name

The seapod name, which is identifier of seapod

Option: hostname

The hostname of your SSH server (DNS or IP).

Option: username

The username to be connected as on the SSH server. Remember to store the generated public key in ~/.ssh/authorized_keys of this users home.

Option: other_ssh_options

Additional ssh options that will be added. This is optional and for testing purposes a verbose output enabled by -v can be useful.