Run Localtonet on a NAS or Home Assistant

Localtonet provides deployment templates that run the Localtonet client as a container on a Docker-capable NAS and on Home Assistant. You add your AuthToken, start the container, and then manage tunnels in the dashboard.

What the templates are #

The download is a small ZIP archive with two templates, five files in all:

The fifth file, README.txt, is a short text version of the steps on this page.

Both templates run the Localtonet client in a container, without prompts, the way the Docker page describes. They are made for AMD64 (Intel and AMD processors) and ARM64. Check which processor your NAS has before you start; a 32-bit ARM NAS cannot run it.

What they are not #

• They are not Synology SPK or QNAP QPKG packages. Nothing appears in the Synology Package Center or the QNAP App Center.
• The Home Assistant template is not a listing in the official Home Assistant store. You install it as a local app.
• They do not contain the container image. Your device pulls the image the templates name, docker.io/localtonet/localtonet, which is the image of the Docker page on Docker Hub.
• They do not give the container the privileges a VPN interface needs. The templates are for tunnels; the VPN feature is not part of them.

Before you start #

• A NAS with Docker and Docker Compose support, or Home Assistant OS / Supervised.
• An AuthToken from My Tokens. Use a token that no other device uses: when a second client connects with the same token, the first one is disconnected.
• The templates ZIP. The download is in the list at the end of this page and on the Downloads page.

Set up a NAS with Docker Compose #

1. Extract the ZIP and copy the nas folder to the NAS #

   Extract the archive on your computer. Copy the nas folder to a shared folder on the NAS that your container manager can use.

2. Create the token file #

   In the nas folder, copy auth-token.example to auth-token. Open auth-token and replace DUMMY_AUTH_TOKEN with your AuthToken, on a single line with nothing else in the file.

   Keep the token file private. Restrict it to your own account on the NAS and do not put it in a shared or synchronised folder that other people can read. The token allows the Localtonet client to connect as this device.

   The file must exist before the container starts. If it is missing, Docker creates a directory named auth-token instead, and the container cannot read a token from it.

3. Leave compose.yaml as it is #

   You do not need to edit compose.yaml. Its image: line names the Localtonet image and the version this ZIP was made for, for example docker.io/localtonet/localtonet:8.6.0. The other lines are explained under What the Compose template does.

4. Start the project #

   Import compose.yaml as a project in your container manager and start it:

   • Synology: in Container Manager, create a project from the nas folder and its compose.yaml.
   • QNAP: in Container Station, create an application from compose.yaml. The file mounts ./auth-token relative to the Compose file, so the token file has to be reachable at that path.
   • Any Docker host with a shell: run the command below from the nas directory.
   Bash

   docker compose up -d

   The exact screens differ between NAS models and versions. Follow your vendor's documentation for creating a project from a Compose file.

5. Create and start a tunnel #

   When the container is running, open the dashboard, create a tunnel with the token you put in the file and select Start, as in the Quick start.

What the Compose template does #

This is the whole file. The tag at the end of the image: line is the Localtonet version your ZIP was made for; 8.6.0 is an example.

services:
  localtonet:
    image: "docker.io/localtonet/localtonet:8.6.0"
    restart: unless-stopped
    network_mode: host
    environment:
      LOCALTONET_HEADLESS: "1"
      LOCALTONET_AUTH_TOKEN_FILE: /run/secrets/localtonet_auth_token
    volumes:
      - ./auth-token:/run/secrets/localtonet_auth_token:ro

Set up Home Assistant OS or Supervised #

Home Assistant OS and Supervised run apps through the Supervisor. The template is a local app that you copy to the device.

1. Copy the app folder #

   Extract the ZIP. Copy the folder home-assistant/localtonet to the local apps directory of your Home Assistant, so that it becomes /addons/localtonet. The folder holds one file, config.json. Do not edit it: it names the app Localtonet, the image docker.io/localtonet/localtonet and the version this ZIP was made for, and it leaves the authtoken option empty for you to fill in later.

2. Reload the app store and install Localtonet #

   Reload the app store in Home Assistant so that it finds the local app, then install Localtonet.

3. Enter your token and start the app #

   Open the app's Configuration page, enter your AuthToken in the authtoken option and start the app. Home Assistant hides the value like a password. The app starts automatically with Home Assistant from then on.

4. Create and start a tunnel #

   Create a tunnel with that token in the dashboard and select Start. To publish Home Assistant itself, create an HTTP tunnel to 127.0.0.1 and the port your Home Assistant listens on. The default port of Home Assistant is 8123. Home Assistant has its own settings for requests that arrive through a proxy; if it rejects them, see the Home Assistant HTTP documentation.

The app uses host networking, so it reaches Home Assistant and the other devices in your network directly. It supports the Home Assistant architectures amd64 and aarch64.

The file home-assistant/repository.json lies outside the folder you copy and is not part of a local installation. It contains placeholder values (DUMMY) for a repository URL and a maintainer; ignore it.

Reach your services #

Both templates use host networking. In a tunnel's Local IP address field:

• 127.0.0.1 is the NAS or the Home Assistant host itself. Use it for the NAS web interface, Home Assistant or any other service on that device, with the port that service listens on.
• A LAN address such as 192.168.1.20 reaches another device in your network.

Logs and updates #

The container writes plain log lines: its connection state, the name of the token it signed in with, and a line whenever a tunnel is added, changes status or is removed. Read them in the log view of your container manager, in the app's Log tab in Home Assistant, or with:

docker compose logs -f localtonet

The line Invalid Localtonet headless configuration. Check the token file or environment settings. means the client found no usable token: the token file is missing or empty, still contains DUMMY_AUTH_TOKEN, or the token is not 33 characters long. Authentication failed: AuthToken was rejected. means the token is well formed but Localtonet does not accept it.

Each templates ZIP is made for one Localtonet version: the Compose file pins it in the tag on the image: line, the Home Assistant app in the version field of config.json. To move a NAS to a newer version, change the tag to a version that Docker Hub lists for the image (see Docker) and run docker compose up -d again (or update the project in your container manager). Your auth-token file stays as it is.

Related pages #