Start Localtonet Automatically on System Boot
By default, Localtonet stops when you close the terminal. Running it as a background service means your tunnels come back online automatically every time your machine restarts no manual intervention, no forgotten sessions. This guide covers every platform: Windows, Linux (systemd), and macOS (launchd).
📋 What's in this guide
Why Run Localtonet as a Service?
When you run Localtonet manually from a terminal, it stops the moment you close that terminal window or when the machine reboots. For most development and testing use cases that's fine. But if you're running a production webhook endpoint, a self-hosted API, a game server, or any service that needs to be reachable 24/7, you need Localtonet to start automatically in the background without any manual steps.
Service Mode
- Starts automatically on every boot
- Runs in the background with no terminal
- Survives user logout and session end
- Managed by the OS (Windows Service / systemd / launchd)
- Restarts automatically if it crashes
Manual Terminal Run
- Stops when you close the terminal
- Stops on every system restart
- Requires you to be logged in
- Easy to forget to restart after reboot
Before You Start
✅ Checklist
- ☑️ Localtonet is already installed on your machine. If not, see the download page.
- ☑️ You have your AuthToken from Dashboard → My Tokens.
- ☑️ You have administrator / sudo privileges on the machine.
- ☑️ On Linux: systemd must be available. Termux does not support service mode.
Installing and managing system services requires elevated permissions.
On WindowsRun Command Prompt or PowerShell as Administrator.
On Linux and macOSPrefix commands with sudo
Step 1 — Install Localtonet as a Service
The same single command works on all three platforms. Localtonet detects the OS automatically and registers the correct service type Windows Service, systemd unit, or launchd job.
sudo localtonet --install-service --authtoken <YOUR_TOKEN>
Windows — Registers a Windows Service visible in services.msc.
Linux — Creates a systemd unit file at /etc/systemd/system/localtonet.service.
macOS — Sets up a launchd job in ~/Library/LaunchAgents/.
Step 2 — Start, Stop, Check Status, and Remove
After installing the service, use these commands to manage it. All commands work identically on Windows, Linux, and macOS.
Start the service
Starts Localtonet as a background service and enables auto-start on every subsequent boot.
sudo localtonet --start-service --authtoken <YOUR_TOKEN>Stop the service
Stops the running Localtonet service. Your tunnels will go offline until the service is started again.
sudo localtonet --stop-service --authtoken <YOUR_TOKEN>Check service status
Returns the current status of the service whether it is running, stopped, or failed.
sudo localtonet --status-service --authtoken <YOUR_TOKEN>Remove the service
Stops and completely unregisters the service from the OS. Localtonet will no longer auto-start on boot.
sudo localtonet --remove-service --authtoken <YOUR_TOKEN>
Once you have run --install-service followed by --start-service,
Localtonet will start automatically on every subsequent boot.
You don't need to run any command again unless you want to stop, update, or remove the service.
Updating Localtonet When a New Version Is Released
Stop the service, replace the binary with the latest version, then start it again. The service registration does not need to be repeated.
# 1. Stop the running service
sudo localtonet --stop-service --authtoken <YOUR_TOKEN>
# 2. Update the binary (Linux one-liner)
curl -fsSL https://localtonet.com/install.sh | sh
# 3. Start the service again
sudo localtonet --start-service --authtoken <YOUR_TOKEN>
Updating is simpler via Homebrew. Run brew upgrade localtonet,
then restart the service with sudo localtonet --start-service --authtoken <YOUR_TOKEN>
Troubleshooting
🪟 "Access Denied" on Windows
You must run Command Prompt or PowerShell as Administrator. Right-click the Start menu → Terminal (Admin) or Command Prompt (Admin), then run the command again.
🪟 Service not appearing in services.msc
Make sure you ran --install-service with the correct AuthToken and Administrator privileges.
If still missing, remove it with --remove-service and reinstall.
Check Windows Event Viewer under Windows Logs → Application for error details.
🐧 Service fails to start on Linux
Check the detailed error output with the command below. Common causes: incorrect AuthToken,
binary not in PATH, or missing execute permission fix with chmod 755 /usr/local/bin/localtonet
🐧 Termux service mode not supported
Termux does not use systemd, so --install-service and related commands are unavailable.
On Android, use the official
Localtonet app from Google Play instead.
🍎 launchd job not starting on macOS
Confirm the plist file exists in ~/Library/LaunchAgents/.
If missing, run --remove-service then --install-service again.
Check macOS Console.app for launchd errors related to Localtonet.
🔑 AuthToken changed or rotated
If you rotate or revoke your AuthToken, the service will stop authenticating.
Remove the old service with --remove-service, then reinstall with your new token.
Command Reference
| Command flag | What it does | Platform |
|---|---|---|
--install-service | Registers Localtonet as an OS service (does not start it yet) | Windows · Linux · macOS |
--start-service | Starts the service and enables auto-start on boot | Windows · Linux · macOS |
--stop-service | Stops the running service | Windows · Linux · macOS |
--status-service | Shows the current service status | Windows · Linux · macOS |
--remove-service | Stops and unregisters the service completely | Windows · Linux · macOS |
systemctl status YOURSERVICENAME | Detailed systemd status and recent logs | Linux only |
journalctl -u YOURSERVICENAME -f | Follow live service logs | Linux only |
launchctl list | grep YOURSERVICENAME | Check if the launchd job is registered | macOS only |
Get-Service -Name "YOURSERVICENAME" | Check Windows Service status via PowerShell | Windows only |
--install-service--start-service--stop-service--status-service--remove-serviceFrequently Asked Questions
Do I need to run --install-service every time I restart the machine?
No. You only run --install-service once. After that, Localtonet starts automatically on every boot without any further commands needed.
Which tunnels start automatically — all of them or only some?
The tunnels that were in Start state in the dashboard are the ones that activate automatically. Tunnels you have stopped from the dashboard remain stopped.
Does service mode work on Raspberry Pi or ARM Linux?
Yes. Localtonet provides ARM and ARM64 Linux builds. Install the correct binary for your architecture, then use the same --install-service command. Raspberry Pi OS uses systemd, so the setup is identical to any other Linux distribution.
Does service mode work on Termux (Android)?
No. Termux is not systemd-based, so service commands are not supported. For persistent background operation on Android, use the official Localtonet app from Google Play.
Can I run --install-service without sudo on Linux?
No. Writing the systemd unit file to /etc/systemd/system/ requires root privileges. Once installed however, the service runs as a system-level process and does not require you to stay logged in as root.
What happens if my AuthToken changes?
The service will stop authenticating. Remove it with --remove-service, then reinstall using your new token: --install-service --authtoken <NEW_TOKEN>.
Keep Your Tunnels Online Around the Clock
Two commands are all it takes --install-service and --start-service.
After that, Localtonet handles the rest on every boot automatically.
