Install Localtonet on OpenWrt

Experimental OpenWrt 24.10 and 25.12+ x64 and ARM64

On this page 12 sections

Before you start
Supported versions and architectures
What is not supported
Check the architecture
OpenWrt 24.10 (opkg)
Storage and memory
What the package installs
Token file and configuration
The token file
The UCI configuration
The service
Logs
Upgrade and remove
OpenWrt 24.10 (opkg)
VPN on OpenWrt
Troubleshooting
Related pages

Run the Localtonet client directly on an OpenWrt router. The package installs the client, a token file, a UCI configuration and a service that starts with the router.

The OpenWrt packages are experimental. They are unsigned files that you install by hand, not packages from a signed OpenWrt feed. Check firmware compatibility, your tunnels and the VPN on your own device before you rely on them.

Before you start #

A router with a supported OpenWrt version and CPU architecture (see the next section).
Root access to the router over SSH.
Internet access on the router during installation. The package manager downloads the dependencies from your firmware's own package feeds.
Enough free storage and memory (see Storage and memory).
An AuthToken from My Tokens that no other device uses.

Supported versions and architectures #

OpenWrt changed its package manager between releases, so there are two package formats. Pick the one for your firmware:

OpenWrt version	Package format	Package manager	Architectures
24.10	IPK	`opkg`	x64, ARM64
25.12 and later	APK v3	`apk`	x64, ARM64

APK here means an OpenWrt package. These .apk files are not Android apps and cannot be installed on a phone. For Android, see Android.

What is not supported #

MIPS, MIPSEL and ARMv7 routers. There are no packages for these architectures.
Installing from a package feed. The packages are local files; your router does not find or update them through opkg update or apk update.
Forcing a package onto a different architecture. Never override the architecture check of the package manager.

Check the architecture #

The package architecture must match your firmware. Ask the router which architectures it accepts:

OpenWrt 24.10 (opkg) #

Bash

opkg print-architecture

OpenWrt 25.12+ (apk)

Bash

apk --print-arch

An x64 router reports x86_64. ARM64 routers report a name that starts with aarch64_, and that name differs between firmware builds. Every package comes with a short instructions file that states the exact package architecture it was built for, for example x86_64 or aarch64_generic. On the Downloads page, choose your package under OpenWrt and open Package setup instructions to read it. Compare that architecture with what your router reports. If they do not match, do not install the package.

Storage and memory #

The package contains the client together with its own runtime, so it is much larger than a typical OpenWrt package. Check the router before you install:

Bash

df -h
free

Flash (overlay). The program files are installed under /usr/lib/localtonet. A router with a small flash chip may need extroot (external storage as the root overlay) to fit them.
RAM and /tmp. When the client starts, it unpacks its native libraries to /tmp/localtonet/bundle. On OpenWrt /tmp is held in RAM, so this space comes out of the router's memory.

What the package installs #

Path	What it is
`/usr/bin/localtonet`	The `localtonet` command.
`/usr/lib/localtonet`	The program files.
`/etc/localtonet/auth-token`	The token file. It contains the placeholder `DUMMY_AUTH_TOKEN` until you replace it. Readable by root only.
`/etc/config/localtonet`	The UCI configuration of the service.
`/etc/init.d/localtonet`	The service script (procd).

The package depends on libc, libgcc1, libstdcpp6, libopenssl3, zlib, ca-bundle, kmod-tun, ip-full, bash, iptables-nft and ip6tables-nft. The package manager installs the missing ones from your firmware's feeds, which is why the setup instructions refresh the package lists first. kmod-tun must match the kernel of the installed firmware, so always take it from that firmware's own feeds.

Token file and configuration #

Installing the package does not connect anything. The service stays off until you have done two things: put your token in the token file and enable the service in UCI. The exact commands for your package are in its Setup instructions at the end of this page; this section explains what they do.

The token file #

/etc/localtonet/auth-token holds your AuthToken on a single line and nothing else. Replace the placeholder DUMMY_AUTH_TOKEN with your token, for example with vi. Keep the file readable by root only (mode 600).

The setup instructions then run the client once with --headless --authtoken-file /etc/localtonet/auth-token --check-config. This checks the file without connecting to Localtonet:

Output	Meaning
`Localtonet headless configuration OK.`	The file contains a well-formed token: 33 characters, no spaces. The check does not prove that the token is valid for your account.
`Invalid Localtonet headless configuration. Check the token file or environment settings.`	The file is missing, still contains the placeholder, or the token is not 33 characters long.

The UCI configuration #

The service reads its settings from /etc/config/localtonet. A fresh installation contains:

/etc/config/localtonet

config localtonet 'main'
    option enabled '0'
    option token_file '/etc/localtonet/auth-token'

Option	What it does	Values
`enabled`	Whether the service starts the client. While it is `0`, starting the service does nothing.	`0` (default) or `1`
`token_file`	Path of the file the client reads the token from.	Default `/etc/localtonet/auth-token`

Show the current values at any time:

Bash

uci show localtonet

The service #

The client runs as a procd service named localtonet. Installing the package registers it to start at boot, but it only starts the client when enabled is 1 and the token file is not empty. After you set enabled to 1 and commit the change, restart the service once; from then on it starts with the router.

Command	What it does
`/etc/init.d/localtonet restart`	Stops and starts the client. Run it after you change the token file or the configuration.
`/etc/init.d/localtonet stop`	Stops the client until the next restart or reboot.
`/etc/init.d/localtonet disable`	Stops starting the service at boot.
`/etc/init.d/localtonet enable`	Starts the service at boot again.

To switch the client off but keep the package installed:

Bash

uci set localtonet.main.enabled='0'
uci commit localtonet
/etc/init.d/localtonet restart

If the client stops unexpectedly, procd starts it again.

Once the client is connected, create and start tunnels in the dashboard with the router's token. A tunnel's Local IP address can be 127.0.0.1 for a service on the router itself, or the LAN address of any device behind the router, for example 192.168.1.20.

Logs #

The client writes to the OpenWrt system log. Show its lines, or follow them live:

Bash

logread -e localtonet
logread -f -e localtonet

Line	Meaning
`Localtonet - headless log`	The client started.
`Connection: …`	The state of the connection to Localtonet.
`AuthTokenName: …`	The name of the token the router signed in with.
`OPEN …`, `ADDED …`, `STATUS …`, `CLOSED …`	A tunnel of this token was found, added, changed status or was removed.
`Authentication failed: AuthToken was rejected.`	Localtonet did not accept the token in the token file.
`AuthToken file missing`	The service is enabled, but the token file does not exist or is empty.

Upgrade and remove #

To upgrade, install the newer package over the old one and restart the service. The token file and the UCI configuration are kept. Both files are also on the list of files that OpenWrt keeps during a firmware upgrade, but the package itself has to be installed again after you flash new firmware.

To remove the client:

OpenWrt 24.10 (opkg) #

Bash

opkg remove localtonet

OpenWrt 25.12+ (apk)

Bash

apk del localtonet

Removing the package stops the service and takes it out of the boot sequence.

VPN on OpenWrt #

The package pulls in what the VPN feature needs on the router: kmod-tun, ip-full, bash, iptables-nft and ip6tables-nft. Routing and firewall behaviour depend on your firmware and your own firewall rules, so test the VPN on your device before you depend on it. See VPN Manager for the feature itself.

Troubleshooting #

The package manager refuses the package because of its architecture

The package was built for a different architecture than your firmware. Compare the output of opkg print-architecture or apk --print-arch with the architecture named in the package's instructions file (Package setup instructions on the Downloads page). Do not force the installation. MIPS, MIPSEL and ARMv7 routers are not supported.

apk refuses to install the file as untrusted

The APK packages are unsigned local files. Installing one needs the --allow-untrusted option, as shown in the package's setup instructions.

The installation fails because a dependency cannot be found

Refresh the package lists first (opkg update or apk update) and make sure the router has internet access. The dependencies come from your firmware's own feeds.

The service is enabled but nothing appears in the log

Check uci show localtonet. If enabled is still 0, set it to 1, commit and restart the service. If the log shows AuthToken file missing, put your token in the file named by token_file.

The client does not start or the router runs out of memory

Check free flash space and memory with df -h and free. The client needs room under /usr/lib/localtonet and in /tmp.

DEB and RPM packagesThe same kind of package for Debian, Ubuntu, Fedora and RHEL. CLI referenceHeadless mode, token files and every other option. Quick startCreate and start a tunnel in the dashboard. AuthTokensCreate a token for the router.

OpenWrt

Experimental. Choose IPK for OpenWrt 24.10 or APK v3 for 25.12+. These APK files are OpenWrt packages, not Android apps.

x64 and ARM64 only. The package architecture must match your firmware; check the package's setup instructions and opkg print-architecture or apk --print-arch. MIPS, MIPSEL and ARMv7 are not supported by these packages. Check available storage and RAM before installing.

OpenWrt 24.10 · x64 · IPK
Setup instructions

1. Install the downloaded package. Open a terminal in the directory containing localtonet-openwrt-24.10-x64.ipk.

Run these commands on the router as root. Confirm that the package architecture matches your firmware before installing.
```
opkg print-architecture
opkg update
opkg install ./localtonet-openwrt-24.10-x64.ipk
```
2. Set your AuthToken. Edit /etc/localtonet/auth-token as root and replace DUMMY_AUTH_TOKEN with your token on a single line. Then protect the file and check the configuration:
```
chmod 600 /etc/localtonet/auth-token
localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
```
3. Start the service. Once the configuration check succeeds:
```
uci set localtonet.main.enabled='1'
uci commit localtonet
/etc/init.d/localtonet enable
/etc/init.d/localtonet restart
logread -e localtonet
```
For upgrades, install the new package and run /etc/init.d/localtonet restart. Your configuration is preserved.
OpenWrt 24.10 · ARM64 · IPK
Setup instructions

1. Install the downloaded package. Open a terminal in the directory containing localtonet-openwrt-24.10-arm64.ipk.

Run these commands on the router as root. Confirm that the package architecture matches your firmware before installing.
```
opkg print-architecture
opkg update
opkg install ./localtonet-openwrt-24.10-arm64.ipk
```
2. Set your AuthToken. Edit /etc/localtonet/auth-token as root and replace DUMMY_AUTH_TOKEN with your token on a single line. Then protect the file and check the configuration:
```
chmod 600 /etc/localtonet/auth-token
localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
```
3. Start the service. Once the configuration check succeeds:
```
uci set localtonet.main.enabled='1'
uci commit localtonet
/etc/init.d/localtonet enable
/etc/init.d/localtonet restart
logread -e localtonet
```
For upgrades, install the new package and run /etc/init.d/localtonet restart. Your configuration is preserved.
OpenWrt 25.12+ · x64 · APK v3
Setup instructions

1. Install the downloaded package. Open a terminal in the directory containing localtonet-openwrt-25.12-x64.apk.

Run these commands on the router as root. Confirm that the package architecture matches your firmware before installing.

This local APK package is unsigned, so installation requires --allow-untrusted.
```
apk --print-arch
apk update
apk add --allow-untrusted ./localtonet-openwrt-25.12-x64.apk
```
2. Set your AuthToken. Edit /etc/localtonet/auth-token as root and replace DUMMY_AUTH_TOKEN with your token on a single line. Then protect the file and check the configuration:
```
chmod 600 /etc/localtonet/auth-token
localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
```
3. Start the service. Once the configuration check succeeds:
```
uci set localtonet.main.enabled='1'
uci commit localtonet
/etc/init.d/localtonet enable
/etc/init.d/localtonet restart
logread -e localtonet
```
For upgrades, install the new package and run /etc/init.d/localtonet restart. Your configuration is preserved.
OpenWrt 25.12+ · ARM64 · APK v3
Setup instructions

1. Install the downloaded package. Open a terminal in the directory containing localtonet-openwrt-25.12-arm64.apk.

Run these commands on the router as root. Confirm that the package architecture matches your firmware before installing.

This local APK package is unsigned, so installation requires --allow-untrusted.
```
apk --print-arch
apk update
apk add --allow-untrusted ./localtonet-openwrt-25.12-arm64.apk
```
2. Set your AuthToken. Edit /etc/localtonet/auth-token as root and replace DUMMY_AUTH_TOKEN with your token on a single line. Then protect the file and check the configuration:
```
chmod 600 /etc/localtonet/auth-token
localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
```
3. Start the service. Once the configuration check succeeds:
```
uci set localtonet.main.enabled='1'
uci commit localtonet
/etc/init.d/localtonet enable
/etc/init.d/localtonet restart
logread -e localtonet
```
For upgrades, install the new package and run /etc/init.d/localtonet restart. Your configuration is preserved.

Read the setup instructions for your package before installing. Packages are unsigned; firmware compatibility, tunnels and VPN need validation on the intended device. Never force a mismatched architecture.

Before you start #

Supported versions and architectures #

What is not supported #

Check the architecture #

OpenWrt 24.10 (opkg) #

OpenWrt 25.12+ (apk)

Storage and memory #

What the package installs #

Token file and configuration #

The token file #

The UCI configuration #

The service #

Logs #

Upgrade and remove #

OpenWrt 24.10 (opkg) #

OpenWrt 25.12+ (apk)

VPN on OpenWrt #

Troubleshooting #

Related pages #

OpenWrt