Command-line reference

Every option of the localtonet console client: signing in with a token, running as a service, running without prompts, choosing a network or an outbound proxy, and the Device Terminal commands.

Before you start #

This page covers the console client for Windows, macOS and Linux, including the client inside the Docker image and the Linux packages. Install it from the install overview. Tunnels are not created on the command line: you create, start and stop them in the dashboard, with the API or with the MCP server. The client connects a device to your account and carries the traffic.

Syntax #

localtonet [options]
localtonet ssh <DEVICE> [--key <KEY>] [--stdio] [-- <COMMAND>]

• Options can be given in any order. Option names are not case-sensitive, except the options of localtonet ssh.
• A value follows its option after a space or an equals sign: --authtoken <YOUR_TOKEN> and --authtoken=<YOUR_TOKEN> are the same.
• An option that needs a value fails with <option> requires a value. when the value is missing.
• --proxy, --proxy-user and --http-transport may be given only once.
• Placeholders such as <YOUR_TOKEN> stand for your own values. Type them without the angle brackets.

With no options, the client starts interactively: it uses the saved token or asks for one, connects and shows a live status table.

localtonet

Quick overview #

Authentication #

--authtoken #

localtonet --authtoken <YOUR_TOKEN>

Signs the device in with an AuthToken from My Tokens. A token is 33 characters long. The client saves it in the profile of the current user, so the next time a plain localtonet is enough.

• Without --authtoken and without a saved token, the client asks Please Enter AuthToken or PIN. You can type the token or a six-digit PIN that the dashboard shows for a token.
• A value that is not a valid token is answered with Wrong Token! and the question is asked again.
• While the client runs, F12 removes the saved token and exits. Ctrl + C exits and keeps it.
• The older spelling without dashes, authtoken <YOUR_TOKEN>, is still accepted.

--ephemeral-token #

localtonet --authtoken <YOUR_TOKEN> --ephemeral-token

Uses the token for this run only. The client does not write the token to the saved settings and does not change a token that is already saved. Use it for automation and temporary sessions.

Service management #

These options register the client with Windows services, launchd on macOS or systemd on Linux. They need administrator rights (sudo on macOS and Linux), and each of them needs the token, because the service is named after it. The full guide is Run as a service.

The service options are not used in headless mode.

Headless mode #

Headless mode is for containers, init systems and scripts. The client never asks a question, does not react to keys, does not save the token, and writes one plain log line per change instead of the status table. The Docker image and the Linux and OpenWrt packages run the client this way.

--headless #

localtonet --headless --authtoken-file /etc/localtonet/auth-token

Starts the client in headless mode. Setting the environment variable LOCALTONET_HEADLESS=1 has the same effect. The client stops cleanly when it receives a termination signal.

The token comes from one of these sources:

A token file always wins over a token passed directly. If a token file is named but cannot be read, the client stops; it does not fall back to another source.

When no usable token is found, the client prints Invalid Localtonet headless configuration. Check the token file or environment settings. and exits with code 2. A usable token is 33 characters long and contains no spaces.

--authtoken-file #

localtonet --headless --authtoken-file <PATH>

Reads the token from a file instead of the command line, so that it does not show up in process lists or shell history. Protect the file, for example with chmod 600. This option is only read in headless mode.

--check-config #

localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config

Checks the token source and exits without connecting. It prints Localtonet headless configuration OK. and exits with code 0 when a well-formed token was found, and the error above with code 2 otherwise. The check is local: it does not tell you whether Localtonet accepts the token. Always combine it with --headless (or LOCALTONET_HEADLESS=1); on its own it is ignored.

The headless log #

Every line after the first starts with a timestamp. The token is never written to the log.

Network selection #

On a device with more than one internet connection, for example Ethernet and a mobile modem, you can choose which one the client uses. The page Network selection explains the feature and the per-tunnel setting.

--network #

localtonet --network

Lists every active network interface with its addresses, checks whether each IPv4 address reaches the internet, and exits. Each line is already written as the options you would pass:

NetworkName: Ethernet
--net Ethernet --ip 192.168.1.20   --> Internet available (public IP 203.0.113.10)
--------------------------------------------------
NetworkName: Mobile
--net Mobile --ip 10.20.30.40   --> No internet access
--------------------------------------------------

IPv6 addresses are listed with IPv6, internet check not available.

--net and --ip #

localtonet --authtoken <YOUR_TOKEN> --net Ethernet --ip 192.168.1.20

Pins the whole client to one network interface. --net is the interface name and --ip is an address of that interface, exactly as --network prints them. Both must be given together. An interface name with spaces can be written as it is or in quotes.

• If the pair cannot be applied, the client waits up to 30 seconds for the interface to come up, which helps when it starts at boot, and then stops with the reason and exit code 2. It does not continue on another network.
• If only one of the two options is given, the client prints --net and --ip must be given together; the default network is used. and continues without a pin.
• On Linux the client adds routing rules for the pinned address. That needs root, or sudo without a password for the ip command.

To use a different connection for a single tunnel instead of the whole client, set the same pair in that tunnel's Arguments setting.

Outbound proxy #

Use these options when the device may only reach the internet through a proxy. They apply to the client's own connections to Localtonet. They do not change how the client reaches your local service.

--proxy #

localtonet --authtoken <YOUR_TOKEN> --proxy http://proxy.example.com:3128
localtonet --authtoken <YOUR_TOKEN> --proxy socks5h://proxy.example.com:1080
localtonet --authtoken <YOUR_TOKEN> --proxy env

The proxy host can be an IPv4 address, a host name or an IPv6 address in square brackets. Credentials can be part of the URL as user:password@host:port; URL-encode special characters in them. Debug output never includes credentials.

--proxy-user #

localtonet --authtoken <YOUR_TOKEN> --proxy socks5h://proxy.example.com:1080 --proxy-user <PROXY_USER>

Sets the proxy user name and asks for the password with a hidden prompt (Proxy password:), so that the password is not on the command line. The password is not saved.

• It needs --proxy env or a proxy URL, and cannot be combined with credentials inside the URL.
• It only works in an interactive terminal. Headless mode and services never prompt: put the credentials in the proxy URL, or use --proxy env with a proxy URL that contains them.
• --install-service refuses --proxy-user and proxy URLs with a password, because a service cannot store them. Install the service with --proxy env and provide the variables in the service's environment.

Proxy environment variables #

These are read only with --proxy env. For each kind of connection the first variable that is set is used:

no_proxy (or NO_PROXY, if the lower-case one is not set) lists hosts that are reached directly:

• Entries are separated by commas. A host or domain matches itself and its subdomains. Matching ignores case and a leading dot.
• IP addresses match exactly; IPv6 addresses may be in square brackets. * bypasses the proxy for every host.
• Address ranges (CIDR), entries with a port and partial wildcards are not supported and are reported as a configuration error.
• no_proxy has no effect when you pass a proxy URL or connect directly.

--http-transport #

localtonet --authtoken <YOUR_TOKEN> --proxy http://proxy.example.com:3128 --http-transport https

Controls how the client carries its server connections when a proxy only lets ordinary web traffic through. With HTTPS transport the client sends that traffic as normal HTTPS requests to a Localtonet gateway instead of opening long-lived raw connections through the proxy.

Any other value stops the client with LOCALTONET_HTTP_TRANSPORT_MODE must be auto, https or raw.

Device Terminal #

Device Terminal gives you a shell on your own devices from the dashboard or over SSH. It runs on Windows, Linux and macOS and needs Localtonet Desktop v8.6 or later. The page Device Terminal describes the feature; these are its command-line parts.

--terminal #

localtonet --terminal enable --authtoken <YOUR_TOKEN>
localtonet --terminal status --authtoken <YOUR_TOKEN>
localtonet --terminal disable --authtoken <YOUR_TOKEN>

All three forms need a token, like a normal start: pass --authtoken, or leave it out to use the saved token. If Localtonet runs as a service on the device, run the command from an Administrator terminal or with sudo. In an interactive terminal, the client keeps running as a normal client after enable, unless Localtonet is already running on the device with this token.

--terminal-user #

sudo localtonet --terminal enable --authtoken <YOUR_TOKEN> --terminal-user <ACCOUNT>

Chooses the account that shells run as, when you enable the terminal as root or as an administrator. Without it, an elevated enable asks Run shells as user:; in a script, where nothing can be asked, it stops with Choose the account for shells with --terminal-user. Without --terminal-user, a command that is not elevated uses the current user.

--pairing-key #

localtonet --terminal enable --authtoken <YOUR_TOKEN> --terminal-user <ACCOUNT> --pairing-key <PAIRING_KEY>

Pairs a device where nobody can read an approval code, for example a server you set up with a script. Create the key in My Devices under Add device with Create one-time key. It is valid for one hour and can be used once. With a pairing key the command does not print a code and does not wait for approval.

localtonet ssh #

localtonet ssh <DEVICE>
localtonet ssh <DEVICE> -- uptime
localtonet ssh <DEVICE> --key <ACCESS_KEY> -- uptime

Opens a shell on one of your devices, or runs one command there and returns its exit code. <DEVICE> is the device name shown in My Devices. ssh must be the first word after localtonet.

Without a key, the command prints Approve this connection in your browser: followed by a link, and waits up to five minutes for you to approve it. If the connection is not approved, it ends with The connection was not approved.

Diagnostics and information #

--debug #

localtonet --debug --proxy env --authtoken <YOUR_TOKEN>

Turns on connection diagnostics on standard error: the proxy routes in use and which setting they come from, the DNS mode, handshake results and the UDP status. Credentials and request bodies are left out. --debug also switches the client to headless mode, so it does not prompt. It is a flag and takes no value.

--version #

localtonet --version

Prints the client version, for example v8.6, and exits.

--help #

localtonet --help

Prints the built-in help and exits. -h does the same.

Environment variables #

Exit codes #

localtonet ssh <DEVICE> -- <COMMAND> returns the exit code of the remote command.

Examples #

localtonet --authtoken <YOUR_TOKEN>

sudo localtonet --install-service --authtoken <YOUR_TOKEN>
sudo localtonet --status-service --authtoken <YOUR_TOKEN>

docker run -d --restart unless-stopped -e LOCALTONET_AUTH_TOKEN=<YOUR_TOKEN> localtonet/localtonet

localtonet --network
localtonet --authtoken <YOUR_TOKEN> --net Mobile --ip 10.20.30.40

export all_proxy=http://proxy.example.com:3128
localtonet --authtoken <YOUR_TOKEN> --proxy env

Related pages #