Install the Localtonet client as a background service so that it starts with the device, keeps running after you log out and needs no open terminal. One command registers it with Windows services, launchd on macOS or systemd on Linux.
Before you start #
- The console client is installed on the device: Windows, macOS or Linux.
- An AuthToken for this device from My Tokens.
- Administrator rights: a terminal opened with Run as administrator on Windows,
sudoon macOS and Linux. - On Linux, a distribution that uses systemd. Termux is not supported; use the Android app there.
Installed from a DEB or RPM package, on OpenWrt or in Docker? Those come with their own way to start at boot. See DEB and RPM packages, OpenWrt and Docker instead of this page.
Install the service #
Run the client once with --install-service and your token. Replace <YOUR_TOKEN> with your AuthToken. Always put --authtoken on this command: the service connects with the token you install it with.
Windows #
Open Command Prompt or PowerShell as Administrator in the folder that contains localtonet, then run:
localtonet --install-service --authtoken <YOUR_TOKEN>The client creates a Windows service with automatic start and starts it. The service is visible in services.msc with the description Localtonet Service. If the service fails, Windows restarts it after one minute.
macOS
sudo localtonet --install-service --authtoken <YOUR_TOKEN>The client writes a launchd job to /Library/LaunchDaemons/<SERVICE_NAME>.plist, loads it and starts it. The job starts at boot, and launchd starts it again if it exits with an error.
Linux
sudo localtonet --install-service --authtoken <YOUR_TOKEN>The client writes a systemd unit to /etc/systemd/system/<SERVICE_NAME>.service, enables it and starts it. The unit starts at boot, and systemd restarts it five seconds after a failure.
If sudo cannot find localtonet, run it with its path, for example sudo ./localtonet from the folder that contains it.
On success the client prints the name of the service:
[CLI] Installed service 'Localtonet_AbCdEfGhI'Installing also starts the service, so no separate start command is needed. You can now create and start tunnels for this token in the dashboard.
The service name #
The service is named Localtonet_ followed by the first nine characters of the token, for example Localtonet_AbCdEfGhI. This page writes <SERVICE_NAME> for it. Because the name comes from the token, you can install one service per token on the same device, and every management command needs the same token to find its service.
What the service runs #
The service starts the same localtonet file from the same location, with the options you gave on the install command. Two things follow from that:
- Do not move or delete the file. The service definition contains its full path. On Linux, if the file is inside
/root, the installer copies it to/usr/local/lib/<SERVICE_NAME>/and the service runs that copy. - Other options are kept. Options such as
--netand--ipor--proxy envon the install command are stored in the service and used on every start. See the CLI reference.
Manage the service #
Use the same token with one of these options. On macOS and Linux, put sudo in front. On Windows, use an Administrator terminal for everything except the status.
| Command | What it does | Output on success |
|---|---|---|
localtonet --status-service --authtoken <YOUR_TOKEN> | Shows the state of the service. | [CLI] Service '<SERVICE_NAME>' status: Running |
localtonet --stop-service --authtoken <YOUR_TOKEN> | Stops the service. Its tunnels go offline. It starts again at the next boot. | [CLI] Stopped service '<SERVICE_NAME>'. |
localtonet --start-service --authtoken <YOUR_TOKEN> | Starts a stopped service. | [CLI] Started service '<SERVICE_NAME>'. |
localtonet --remove-service --authtoken <YOUR_TOKEN> | Stops the service and removes its registration. The localtonet file itself stays. | [CLI] Removed service '<SERVICE_NAME>'. |
The status is one of these values:
| Status | Meaning |
|---|---|
Running | The service is running. |
Stopped | The service is installed but not running. |
Installing | The service is starting. |
NotFound | No service is installed for this token. |
Paused | Windows only: the service was paused. |
Error | The service failed, or its state could not be read. |
Unknown | The service manager returned a state the client does not recognise. |
You can also use the tools of the operating system with the service name:
Windows #
Open services.msc and find <SERVICE_NAME>, or use sc in an Administrator terminal:
sc query <SERVICE_NAME>
sc stop <SERVICE_NAME>
sc start <SERVICE_NAME>macOS
sudo launchctl print system/<SERVICE_NAME>Linux
systemctl status <SERVICE_NAME>
sudo systemctl restart <SERVICE_NAME>Where the service is registered and where its logs are #
| System | Registration | Logs |
|---|---|---|
| Windows | A Windows service named <SERVICE_NAME>, start type automatic, running under the LocalSystem account. | The service has no console window and the installer sets up no log file. Check the service state, and the device and its tunnels in the dashboard. |
| macOS | /Library/LaunchDaemons/<SERVICE_NAME>.plist, a system-wide launchd job. | /var/log/<SERVICE_NAME>.out.log and /var/log/<SERVICE_NAME>.err.log |
| Linux | /etc/systemd/system/<SERVICE_NAME>.service, enabled for multi-user.target. | The systemd journal: journalctl -u <SERVICE_NAME> -f |
The service does not print the tunnel table that the client shows in a terminal. For the state of your device and its tunnels, use the dashboard.
Change the token #
To change the token of a device, remove the service with the old token and install it again with the new one:
sudo localtonet --remove-service --authtoken <OLD_TOKEN>
sudo localtonet --install-service --authtoken <NEW_TOKEN>Things to know #
- One client per token. While the service runs, do not start another Localtonet client with the same token, on this device or another one. A second client that connects with a token disconnects the first.
- Updating the client. The service keeps running the file that its definition points to. Stop the service, replace that file with the new version, and start the service again.
- Proxy passwords are not stored. The install command refuses a proxy URL that contains a password and the option
--proxy-user. Install with--proxy envand set the proxy variables in the environment of the service. - Device Terminal. If the device runs Localtonet as a service, run
localtonet --terminal enablefrom an Administrator terminal or withsudo, so that the service can use the result. See Device Terminal.
Troubleshooting #
| Message | Cause and fix |
|---|---|
[CLI] Install failed: '…' requires elevated (admin/root) privileges. | The command was run without administrator rights. Open the terminal as Administrator on Windows, or use sudo on macOS and Linux. On Windows and Linux the same message appears for start, stop and remove. |
[CLI] Install failed: followed by Service '<SERVICE_NAME>' already exists. (Windows), Systemd unit already exists for … (Linux) or Plist already exists for … (macOS) | A service for this token is already installed. Use --start-service to start it, or --remove-service first if you want to install it again. |
Service installation cannot persist proxy passwords. Use --proxy env and supply credentials in the service's runtime environment. | The install command contained --proxy-user or a proxy URL with a password. Use --proxy env instead. |
[CLI] Start failed: … on Windows right after installing | The service is already running, because installing starts it. Check with --status-service. |
Status is NotFound | No service exists for the token you passed. Check that it is the token you installed the service with. |
Status is Running but the device is offline in the dashboard | Check the token: copy it again from My Tokens, remove the service and install it again. Also make sure no other client uses the same token. |
