CLI

Your first tunnel#

localport http 3000 --token YOUR_TOKEN --region eu

Protocol first, port second. That forwards port 3000 on this machine to a public HTTPS address, which the agent prints as soon as it connects. The token comes from the tunnel's page in the dashboard.

Commands at a glance#

Command	What it does
http, tcp, tls	Open a tunnel to a local service, followed by the port to forward.
connect	Join a fleet as a device, or run every entry in a config file.
access	Reach a device's ports on a fleet, presenting a certificate.
setup	Approve this machine, once, so it can reach a fleet.
login	Approve yourself, so you can reach a fleet from this machine.
identity	See, renew, or remove what this machine has been approved for.
version	Print the version, commit, and build date.

Opening a tunnel#

Give localport a protocol and a port, and it forwards traffic from a public address to a local service.

Positional form#

The shortest form, for a service on the machine running the agent. Protocol first, port second.

localport http 3000 --token YOUR_TOKEN --region eu
localport tcp 5432 --token YOUR_TOKEN --region eu
localport tls 8443 --token YOUR_TOKEN --region eu

The recognised protocols are http, https, tcp, and tls. A host:port pair also works in the second position:

localport http localhost:3000 --token YOUR_TOKEN

Forwarding to another machine#

To reach a service that is not on this machine, such as a NAS, a container, a Raspberry Pi, or another server on the LAN, use --local with a scheme. The scheme sets the protocol.

localport --token YOUR_TOKEN --local tcp://192.168.1.50:5432 --region eu
localport --token YOUR_TOKEN --local http://app.local:8080 --region eu

--local and the positional form cannot be combined. Using both is an error, so neither one silently wins.

Which protocol to choose#

Protocol	Use it for
http	Web apps and APIs: Next.js, Django, Rails, Flask, Express, anything serving HTTP. https is accepted as an alias.
tcp	Databases, game servers, SSH, MQTT, gRPC, and anything else over raw TCP.
tls	TLS pass-through, where your local service terminates TLS itself and the bytes should reach it still encrypted.

Tunnel flags#

Flag	Default	What it does
--token, -t		Tunnel token from the dashboard. See LOCALPORT_TOKEN below for keeping it off the command line.
--local, -l		Local service to forward to, optionally with a scheme: tcp://192.168.1.50:5432, http://app.local:8080, or a bare host:port.
--region		Region to connect through: eu, us, or ap. Omit to use the default entry point.
--proto	http	Protocol, when --local carries no scheme. Overridden by a scheme or by the positional form.
--name	default	Names this connection. Sent as the device name, and required for fleet tunnels, where it becomes the device's own address.
--config		Path to a YAML file describing one or more tunnels. See Configuration.
--noui	false	Turn off the live status panel and write plain log lines instead. Enabled automatically when output is not a terminal.
--log-requests	false	Log one line per HTTP request. Applies to HTTP tunnels in plain mode only.
--no-inspect	false	Never parse HTTP requests for the live panel, even when it is showing. Wins over --log-requests.
--no-mux	false	Give each inbound connection its own connection to Localport instead of multiplexing them over one. A troubleshooting flag, not a tuning one.
--version		Print the version and exit.

Only --token and --local have short aliases (-t, -l). There is no short form for --region.

Output modes#

Live panel (default). The terminal shows tunnel state, the public address, the region, and a table of active connections with bytes in and out, updating as traffic arrives.

Plain mode. With --noui, or automatically whenever output is redirected to a file, a pipe, journald or a CI log, every event becomes one timestamped line. Startup, state changes, the public address on connect, each connection opening and closing with its originating IP, bytes in and out, and duration. While traffic is flowing, a one-line usage summary is written every 60 seconds.

Plain mode is the right choice for anything unattended. It is what the systemd unit and launchd daemon in Installation use.

localport connect#

Join a fleet as one device. The ports that device serves are set in the dashboard, so this command names the machine and nothing else.

localport connect --token TOKEN [--name DEVICE] [--host ADDRESS]

Leave --name off and the machine's hostname is used. --host is where this device's traffic goes on your network, defaulting to localhost. Point it at another address and this machine fronts equipment that cannot run the agent itself.

Flag	Default	What it does
-t, --token		Fleet token. Also read from LOCALPORT_TOKEN or LOCALPORT_TOKEN_FILE.
--name	hostname	Device name. It becomes the device's address and is what grants refer to.
--host	localhost	Where this device sends traffic. An address with no scheme and no port.
--region	eu	Which region this agent connects to.
--config		Path to a YAML file describing several tunnels and devices at once.
--noui	off	Print plain log lines instead of the live display.
--no-mux	off	Give each inbound connection its own connection to the edge.
--no-inspect	off	Do not parse HTTP requests for the live view.
--log-requests	off	Print one line per HTTP request, without the live display.

localport connect --token tok_YOUR_TOKEN --name plc-01 --host 192.168.1.100
localport connect --config localport.yaml

localport access#

Reach a device's ports on a fleet from this machine. The agent presents a client certificate, opens one connection to the device, and forwards each port you ask for over it. Whatever you point at a local port reaches the remote service, with no awareness of Localport.

localport access DEVICE-ADDRESS -L [LOCAL:]REMOTE [flags]

The device address#

The address is the device's own host, as the Devices tab shows it. It carries no scheme and no port: each port behind it carries its own protocol, and you choose the port with -L.

gw-01-example.eu.localport.dev

A pasted https:// prefix and a trailing path are accepted and ignored.

Forwarding ports#

-L takes the local port first, in the order ssh -L uses, and is repeatable:

What you write	What it does
-L 5020:502	Listens on 127.0.0.1:5020 and reaches the device's port 502.
-L 502	Reaches port 502 on a local port the system picks, printed when it binds.

Every forward travels over one mutual-TLS connection to the device:

localport access gw-01-example.eu.localport.dev -L 8080:80 -L 5020:502

For SSH, hand the connection to it directly with --stdio, which carries one connection over standard input and output:

ssh -o ProxyCommand="localport access gw-01-example.eu.localport.dev --stdio 22" user@gw-01

Choosing the credential#

With no credential flag at all, the agent presents the identity this machine already holds from localport setup or localport login and renews it in the background. That is the intended path: nothing to copy onto the machine, and no file that quietly expires while somebody is away.

localport setup lps_...                                          # once, per machine
localport access gw-01-example.eu.localport.dev -L 3001:3000    # from then on

Supply a file only for a credential Localport did not issue, such as one from your own certificate authority.

Credential	How it authenticates
_(no flag)_	The stored identity on this machine. Renews itself.
--audience	A CI pipeline's own OIDC identity. No secret is stored anywhere.
--pem	A PEM file holding the client certificate, its key, and the fleet CA.
--p12	A PKCS#12 archive, with the password supplied separately.

--pem and --p12 files must be mode 0600 or stricter and owned by the user running the command. A more permissive file is refused, since other accounts on the machine could read the private key. A symlink is refused too.

Access flags#

Flag	Default	What it does
-L		Forward [local:]remote. Repeatable, once per device port.
--stdio		Carry one connection to this device port over standard input and output.
--local-addr	127.0.0.1	Address to bind local ports to. Loopback by default, so nothing else on your network reaches them.
--identity		Which stored credential to present when this machine holds several. See selectors below.
--pem		PEM file with client certificate, key, and fleet CA.
--p12		PKCS#12 archive (.p12 or .pfx).
--p12-pass		Archive password inline. Visible in shell history and to ps, so prefer the two below.
--p12-pass-file		File to read the archive password from.
--p12-pass-env	LOCALPORT_P12_PASSWORD	Environment variable to read the archive password from.
--audience		OIDC audience for a CI workload identity. Also settable with LOCALPORT_OIDC_AUDIENCE.
--config		Path to an access YAML file describing several devices at once.

The password is resolved in order: --p12-pass, then --p12-pass-file, then the environment variable named by --p12-pass-env. A password shorter than 12 characters produces a warning but is still accepted, because an archive exported elsewhere is your own key management to run.

Reaching a tunnel from CI#

A pipeline authenticates with the identity its own platform mints, so there is no secret in the repository, none in the CI secret store, and nothing written to disk. On GitHub Actions, add permissions: { id-token: write } to the job:

localport access gw-01-example.eu.localport.dev --audience lpa_... -L 2222:22

On other platforms, put the token in LOCALPORT_OIDC_TOKEN and the audience in LOCALPORT_OIDC_AUDIENCE. See CI/CD with OIDC.

localport setup#

Give this machine a credential of its own, so it can reach a fleet without anyone copying a certificate onto it. Run once per machine.

localport setup TOKEN [--wait DURATION]

An operator creates the setup key in the dashboard and gives you one string. The machine spends it once, generates a private key that never leaves it, and renews its own certificate from then on. There is no long-lived secret to rotate afterwards and no certificate file to copy around.

The key is single use. Prefer the environment over an argument. An argument is visible in shell history and in a process list.

LOCALPORT_SETUP_TOKEN=lps_... localport setup

Flag	Default	What it does
--wait	60s	How long to keep retrying when Localport cannot be reached, with backoff. Covers a machine that boots before its network is ready. Use --wait 0 in CI for exactly one attempt.

--wait applies only to conditions that waiting can fix. A refused key fails immediately at any setting, A refusal will still be a refusal in sixty seconds.

localport login#

Signs you in and places a short-lived certificate on this machine.

localport login

It prints a code, you approve it in the dashboard in any browser, and the certificate arrives. Nothing has to be transmitted to the machine beforehand, so it works over SSH into a jump box where a browser redirect back to localhost cannot.

The certificate lasts hours and does not renew. Run localport login again when it expires. For a machine that should keep itself working unattended, use localport setup instead. See Member Access.

localport identity#

Inspects and manages the credentials stored on this machine.

localport identity list   [--identity SELECTOR]
localport identity renew  [--identity SELECTOR]
localport identity remove SELECTOR

Subcommand	What it does
list	Every credential, with its team, source, expiry, and when it renews. Writes to stdout so it can be piped.
renew	Force a renewal now. Renewal normally happens on its own inside localport access. Run this from a daily timer on a machine that is not permanently connected.
remove	Delete a credential from this machine. It does not revoke anything. The certificate stays valid until it is revoked in the dashboard.

Selectors#

A selector names one credential. Use the shortest form that matches exactly one:

gw-01                     a bare identity
<team>/gw-01              narrowed to one team
<team>/client/gw-01       fully qualified

Two segments mean team and identity, never kind and identity. When several credentials match, the error lists the full form of each so it can be pasted back. LOCALPORT_IDENTITY sets a default.

A selector that was supplied and matches nothing, or matches several, is an error and never a prompt. A typo must not open a menu from which the wrong identity gets chosen.

Where credentials are stored#

~/.localport/identity/<team>/<kind>-<identity>/
  cert.pem     the certificate and its issuing chain
  key.pem      the private key, generated here, never transmitted
  meta.json    identity, team, source, expiry, and renewal deadline

Directories are mode 0700 and files 0600. Set LOCALPORT_HOME to keep them elsewhere. The service templates in Installation do exactly that, so a system account has somewhere to write. A machine running a service with no home directory falls back to a machine-wide state directory.

localport version and help#

localport version     # version, commit, and build date
localport help        # command list and examples

--version and -version are accepted as aliases of version, and --help and -h of help. Every command also prints its own usage when given -h.

Environment variables#

Every secret the CLI takes has an environment variable and a _FILE counterpart, so a token never has to appear in a command line or a process list. The full table, the precedence order and the rules on a secret file are on Environment Variables.

Configuration files#

connect and access both accept --config for running several things from one file.

localport connect --config localport.yaml   # tunnels and fleet devices
localport access --config access.yaml       # forwards from fleet devices

${VAR} references are substituted when an agent config is read, so a file you commit holds no secrets. See Configuration for the full schema and worked examples.

Reconnects, limits, and exit behaviour#

• Reconnection is automatic. Network drops, a sleeping laptop, a changed Wi-Fi network, and brief service interruptions all reconnect on their own, with backoff. The public address does not change.
• A lost network is detected, not waited out. If the machine changes address or wakes from sleep, the agent probes the connection immediately instead of sitting on a dead socket, so a reconnect takes seconds.
• Limits are reported, not guessed at. When a bandwidth or connection limit is reached, the agent prints which one and exits cleanly instead of reconnecting in a loop.
• Errors carry a reference code. A terminal failure prints a short code alongside the message, shown in the panel border or appended to the log line. Quote it to support and it identifies the exact refusal.

---

Frequently asked questions#

How do I keep my token out of my shell history?

Set LOCALPORT_TOKEN, or better, point LOCALPORT_TOKEN_FILE at a file that only your user can read. The same pattern works for a setup key with LOCALPORT_SETUP_TOKEN_FILE. Secret files must be mode 0600 or stricter and owned by you. Anything more permissive is refused.

What is the difference between localport setup and localport login?

setup is for a machine. It spends a single-use setup key, keeps a private key generated locally, and renews its own certificate indefinitely. login is for a person. It signs you in through the dashboard and gives you a certificate that lasts hours and does not renew, so re-running it is how you get another. Off-boarding a person is removing them from the team. Retiring a machine is revoking its certificate.

Which short flag aliases exist?

Only -t for --token and -l for --local when opening a tunnel, and -p for --port on access. Everything else is long-form only. Guides on this site use long-form flags throughout, because a command pasted into a runbook is read far more often than it is typed.

Does localport access need a certificate file?

Usually not. With no credential flag it presents whatever this machine already holds from localport setup or localport login, and renews it in the background. --pem and --p12 exist for credentials Localport did not issue, such as ones from your own certificate authority, or for tools that need a file of their own.

Can I run several tunnels from one process?

Yes. Put them in a YAML file and run localport connect --config localport.yaml. Each tunnel opens its own connection, so one failing does not disturb the others. The same file can list fleet devices, under one fleet token. See Configuration.

What does --no-mux do, and should I use it?

By default the agent carries every inbound connection over a single multiplexed connection to Localport, which removes a round trip per connection. --no-mux gives each one its own connection instead. It exists for diagnosing an unusual network, not for tuning. Nothing breaks either way: if multiplexing cannot be established, the agent falls back on its own.

Why does my live panel disappear in CI or under systemd?

That is deliberate. The agent detects that output is not a terminal and switches to plain mode, where each event is one timestamped line. You can force it with --noui and force plain output regardless of detection with TERM=dumb.

Does localport identity remove revoke the certificate?

No, and the distinction matters. remove deletes the credential from this machine only. The certificate stays valid and would still be accepted if someone held a copy. To actually withdraw access, revoke it in the dashboard, which also closes any connections currently using it. See Certificates.

What to read next#

• Configuration. The YAML schema for running several tunnels at once.
• Environment Variables. Every variable, and how to keep tokens off the command line.
• Quick Start. Create a tunnel and reach it from the internet.
• Remote Access. Require a client certificate to connect.
• Setup Keys. Give a machine a credential that renews itself.
• Member Access. Sign a person in with localport login.
• CI/CD with OIDC. Reach a tunnel from a pipeline with no stored secret.