این صفحه هنوز به فارسی در دسترس نیست و به زبان انگلیسی نمایش داده میشود.
Run Localtonet in Docker
در این صفحه 12 بخش
- Before you start
- Steps
- Pull the image
- Start the container with your token
- Create and start a tunnel
- How the container runs
- Run in the background and restart automatically
- Ways to pass the token
- Docker Compose
- Reach your service from the container
- Read the log
- Update
- Image archives for hosts without registry access
- Troubleshooting
- Related pages
The official image localtonet/localtonet runs the Localtonet client in a container. Pass your AuthToken, then create and start tunnels in the dashboard as usual.
Before you start #
- Docker on a 64-bit host. The image is published for
linux/amd64andlinux/arm64, and Docker picks the one that matches your host. For a 32-bit ARM device, use the Linux build instead. - An AuthToken from My Tokens. Give each container its own token: when a second client connects with the same token, the first one is disconnected.
Steps #
-
Pull the image #
Pulling first makes sure you run the current version and not an older image that is still on the host.
Bashdocker pull localtonet/localtonetThe image is on Docker Hub. Besides
latest, Docker Hub lists a tag for each version if you want to pin a release. -
Start the container with your token #
Everything after the image name is passed to the Localtonet client. Replace
<YOUR_TOKEN>with your AuthToken.Bashdocker run localtonet/localtonet --authtoken <YOUR_TOKEN>The container prints its connection state and stays in the foreground. Press Ctrl + C to stop it.
-
Create and start a tunnel #
Open the dashboard, create a tunnel with the token you gave the container, and select Start. The Quick start shows the form. Read Reach your service from the container before you fill in Local IP address, because
127.0.0.1means something different inside a container.
How the container runs #
The image starts the client in headless mode. That changes three things compared with the client on a desktop:
- It never asks a question. If the token is missing or malformed, the container prints an error and exits with code 2.
- It writes plain log lines instead of the live status table, also when you start it with
-it. - It does not save the token. The image declares no volumes, so pass the token every time a container is created: on the command line, in an environment variable or as a file.
Tunnels are not configured in the container. You create, start and stop them in the dashboard, and the container picks them up over its connection.
Run in the background and restart automatically #
Use -d to detach and a restart policy so that Docker starts the container again after a reboot or a crash:
docker run -d \
--name localtonet \
--restart unless-stopped \
localtonet/localtonet --authtoken <YOUR_TOKEN>Manage it with the usual Docker commands:
| Command | What it does |
|---|---|
docker ps | Lists running containers. |
docker logs -f localtonet | Follows the client's log. |
docker stop localtonet | Stops the client. Its tunnels go offline. |
docker start localtonet | Starts it again with the same token. |
docker rm -f localtonet | Removes the container. |
Ways to pass the token #
A token on the command line is visible in docker inspect and in the host's process list. The image also reads the token from the environment or from a file:
| Source | How to use it | Notes |
|---|---|---|
--authtoken <YOUR_TOKEN> | Argument after the image name. | Simplest. Wins over LOCALTONET_AUTH_TOKEN. |
LOCALTONET_AUTH_TOKEN | Environment variable that holds the token. | Used when no --authtoken argument is given. |
LOCALTONET_AUTH_TOKEN_FILE | Environment variable that holds the path, inside the container, of a file that contains only the token. | A token file always wins over a token passed directly. The argument --authtoken-file <PATH> does the same. |
The image itself sets LOCALTONET_HEADLESS=1. You do not need to set it.
With a token file, keep the token out of the container definition and mount it read-only:
printf '%s' '<YOUR_TOKEN>' > auth-token
chmod 600 auth-token
docker run -d \
--name localtonet \
--restart unless-stopped \
-e LOCALTONET_AUTH_TOKEN_FILE=/run/secrets/localtonet_auth_token \
-v "$(pwd)/auth-token:/run/secrets/localtonet_auth_token:ro" \
localtonet/localtonetCreate the token file before you start the container. If the file does not exist, Docker creates a directory with that name and the client cannot read a token from it.
To check a token source without connecting, add --check-config. The client checks that the token is present and well formed (33 characters, no spaces), prints Localtonet headless configuration OK. and exits. It does not ask the server whether the token is valid.
docker run --rm \
-e LOCALTONET_AUTH_TOKEN_FILE=/run/secrets/localtonet_auth_token \
-v "$(pwd)/auth-token:/run/secrets/localtonet_auth_token:ro" \
localtonet/localtonet --check-configDocker Compose #
The same setup as a Compose file. Put the token in a file named auth-token next to compose.yaml:
services:
localtonet:
image: localtonet/localtonet
restart: unless-stopped
environment:
LOCALTONET_AUTH_TOKEN_FILE: /run/secrets/localtonet_auth_token
volumes:
- ./auth-token:/run/secrets/localtonet_auth_token:rodocker compose up -d
docker compose logs -f localtonetWhen the service you want to publish is in the same Compose project on a Linux host, publish its port on the host and run the Localtonet container with host networking. The tunnel's local address must be an IP address, so a Compose service name such as web cannot be used for it:
services:
web:
image: nginx
ports:
- "8080:80"
localtonet:
image: localtonet/localtonet
restart: unless-stopped
network_mode: host
environment:
LOCALTONET_AUTH_TOKEN_FILE: /run/secrets/localtonet_auth_token
volumes:
- ./auth-token:/run/secrets/localtonet_auth_token:roFor this example, set the tunnel's local address to 127.0.0.1 and its local port to 8080.
For a NAS or Home Assistant, ready-made templates are on the NAS and Home Assistant page.
Reach your service from the container #
The tunnel's Local IP address and Local port tell the client where your service is. The client connects from inside the container, where 127.0.0.1 is the container itself and not your machine. Enter an IP address: the client does not look up Docker names such as host.docker.internal, a Compose service name or a container name. Use the value that matches where the service runs:
| Where the service runs | Local address to enter | What else is needed |
|---|---|---|
| On the Docker host, Linux | 127.0.0.1 | Start the container with --network host (Compose: network_mode: host). The container then shares the host's network. |
| On the Docker host, without host networking (including Docker Desktop on Windows or macOS) | The host's LAN IP address, for example 192.168.1.10 | The service must listen on an address the container can reach, not only on 127.0.0.1, and the host's firewall must allow the connection. |
| In another container | 127.0.0.1 with --network host on Linux, otherwise the host's LAN IP address | Publish the port of that container on the host (-p, Compose: ports) and use the published port as the tunnel's local port. |
| On another device in your network | That device's LAN IP address, for example 192.168.1.20 | Nothing. |
docker run -d \
--name localtonet \
--restart unless-stopped \
--network host \
localtonet/localtonet --authtoken <YOUR_TOKEN>You can change the address of an existing tunnel in its settings under Local address. See the settings reference.
Read the log #
docker logs -f localtonet shows one line per change. Every line after the first starts with a timestamp:
| Line | Meaning |
|---|---|
Localtonet - headless log | The client started. |
Connection: … | The state of the connection to Localtonet. A new line appears when it changes. |
AuthTokenName: … | The name of the token the container signed in with, as shown in My Tokens. |
OPEN …, ADDED … | A tunnel of this token. OPEN is used for tunnels that exist when the client starts, ADDED for tunnels that appear later. |
STATUS … | The status of a tunnel changed. |
CLOSED … | A tunnel was removed from this client. |
Authentication failed: AuthToken was rejected. | Localtonet did not accept the token. |
The token itself is never written to the log.
Update #
Pull the image again and recreate the container:
docker pull localtonet/localtonet
docker rm -f localtonet
docker run -d --name localtonet --restart unless-stopped localtonet/localtonet --authtoken <YOUR_TOKEN>With Compose, run docker compose pull and then docker compose up -d. To always start from the newest image, add --pull always to docker run.
Image archives for hosts without registry access #
If the host cannot reach Docker Hub, download the image as a TAR archive on another machine, copy it over and load it:
| Architecture | Archive |
|---|---|
| AMD64 | localtonet-docker-amd64.tar |
| ARM64 | localtonet-docker-arm64.tar |
docker load --input localtonet-docker-amd64.tardocker load prints what it loaded. If it prints an image ID instead of a name, give the image a name before you run it:
docker tag <IMAGE_ID> localtonet/localtonet
docker run -d --name localtonet --restart unless-stopped localtonet/localtonet --authtoken <YOUR_TOKEN>Troubleshooting #
The container exits right away with "Invalid Localtonet headless configuration"
The full message is Invalid Localtonet headless configuration. Check the token file or environment settings. The client found no usable token: nothing was passed, the value is not 33 characters long, it contains a space or line break in the middle, or the token file path does not exist in the container. If you mount a token file, check on the host that it is a file and not a directory. With a restart policy the container keeps restarting until you fix the token, so read docker logs localtonet.
The log shows "Authentication failed: AuthToken was rejected."
The token is well formed but Localtonet does not accept it. Copy it again from My Tokens and recreate the container.
The tunnel is started but the public address does not reach my service
Check the tunnel's local address. 127.0.0.1 only works with --network host on Linux. Otherwise use the host's LAN IP address. A name such as host.docker.internal or the name of another container does not work in this field, as described in Reach your service from the container.
The container keeps losing its connection
Make sure no other client uses the same token. A second client that connects with the token disconnects the first one. Create one token per container or device in My Tokens.