Fleets

Q: Does every device need its own token?

No. One token serves the whole fleet, and the --name flag is what separates the machines. Cutting one machine off is done by removing that device or by narrowing its grants, never by rotating a token every other machine shares.

Q: How do I name a device?

Pass --name when you start the agent, or pick the machine from the roster in the dashboard's Connect panel. Names are lowercase letters, numbers and dashes, up to 48 characters, and unique on the fleet. Pick names that share a prefix, such as device1 and device2 , so a single grant naming device* covers the ones you add later.

Q: How do I run this on a machine with no terminal?

Add --noui , which prints plain log lines instead of the live display. That is the form to use inside systemd units, Docker containers and CI runners, where there is no interactive terminal and logs get collected.

Summary

A fleet is one tunnel that carries many machines. You create it once, run the Localport agent on each machine with a name, and every machine gets a public address of its own such as device1-example.eu.localport.dev. Only callers holding a certificate your team trusts can reach any of them.

Fleets are on the Pro and Enterprise plans. See pricing. You will also need the agent installed on each machine: Installation.

How a fleet works#

A fleet gives every machine its own address behind a single tunnel and a single token. You create the fleet in the dashboard, then start the agent on each machine with --name. That name becomes the machine's address and is what you write grants against.

Machines connect outward to Localport and hold the connection open. Nothing on your side listens for inbound connections, so a fleet works behind NAT, carrier-grade NAT or a firewall you do not administer.

A fleet carries HTTP and TCP. That covers web services, APIs, SSH, Postgres, MQTT, VNC and anything else built on TCP. A fleet does not carry TLS passthrough. Use tcp for a service that holds a certificate of its own.

Every fleet is private from the moment it exists. A caller has to present a client certificate and hold a grant covering the device it reaches, and neither check can be turned off. Grants and Access covers writing those grants.

Create a fleet#

Open Fleets under Remote Access in the dashboard sidebar, then select Create fleet.

The New Fleet panel asks for four things:

Name identifies the fleet in the dashboard and seeds its subdomain.
Region decides where your machines connect and where traffic is served. EU, US and Asia Pacific are available.
Custom Domain is optional and can be attached later from settings. A fleet needs a wildcard domain. Each device is served at its own label under it.
Force HTTPS redirects plain HTTP requests to HTTPS. It is on by default.

Select Create Fleet and the panel moves to its Connect step with the command already built.

Name the fleet, pick a region, attach a wildcard domain. The Connect step rewrites the command as you add the device name and turn off the live UI.

Connect a machine#

The Connect panel builds the command for you. The controls that matter on a fleet:

Preset fills in a common local service, or leave it on Custom.
Protocol is HTTP or TCP, matching what the machine actually serves.
Local Address is where the service listens on that machine, localhost:3000 by default.
Device is marked Required and is a picker over the fleet's roster. Choose a machine already on the fleet, or type a new name.
Run without the live UI turns off the interactive terminal display and prints plain log lines. Turn it on for servers, systemd units, Docker containers and CI.

Copy the command and run it on the machine:

localport http 3000 --token tok_YOUR_TOKEN --region eu --name device1

That forwards port 3000 on the machine and registers it as device1. The device appears on the Devices tab as soon as the agent connects.

A device name is required on a fleet, and the dashboard blocks the copy until you supply one. The name becomes the device's address and is what grants refer to.

On a server, add --noui:

localport tcp 22 --token tok_YOUR_TOKEN --region eu --name device2 --noui

--noui replaces the live terminal display with plain log lines, which is the form to use inside systemd units, Docker containers and CI runners.

One token serves every machine on the fleet. The --name flag is what separates them.

Where each device answers#

A device's address joins its own name to the fleet's subdomain:

device1-example.eu.localport.dev

TCP devices also answer on the fleet's shared host, each on the port assigned to it. Both of these reach the same device:

tcp://device1-example.eu.localport.dev:20411
tcp://example.eu.localport.dev:20411

Every row carries the device's own address, with a copy button beside it.

A device name is lowercase letters, numbers and dashes, up to 48 characters, and unique on the fleet. A second agent claiming a name already in use is refused, never renamed.

The name is permanent once the machine has connected. It is the device's address and what every grant refers to. You can still give a device a display name from the Devices tab for the list, and the address and its grants keep using the original.

Run several devices from one machine#

One host can serve several devices. Put them in a config file, one endpoint per device:

version: 1
spec:
  token: ${env.LOCALPORT_TOKEN}
  region: eu
  endpoints:
    - name: device1
      url: http://192.168.10.21:8080
    - name: device2
      url: tcp://192.168.10.22:22
    - name: device3
      url: http://localhost:3000

LOCALPORT_TOKEN=tok_YOUR_TOKEN localport --config localport.yaml

One agent process serves all three, and each endpoint holds its own connection.

Each endpoint becomes its own device, with its own address, its own connection and its own grants. Use it to reach equipment that cannot run the agent itself, over the local network from a host that can.

Every url needs a port

The local side is dialled directly, so http://192.168.10.21 fails with missing port in address. A bare number is the one shorthand: url: 3000 becomes localhost:3000. ${env.VAR} keeps the token out of the file.

The Devices tab#

Every machine that has ever connected appears here, online or not, with a count of how many are up. Each row carries:

Column	Holds
Device	The name, a dot for its state, and the protocol it serves
Address	The device's own URL, with a copy button
Activity	Requests or connections handled, and bytes in and out
Session	How long it has been online, or when it was last seen
IP	The address the agent is connecting from

The status dot carries three states: online, offline, and never connected. Filter the roster by Online, Offline or Never seen, and sort it by name, online first, or recently seen.

Each row's menu reaches the rest of Remote Access: Give access writes a grant covering that device, Who can reach lists everything that already does, and Access log shows what actually connected.

The Devices tab: the roster online and offline, each machine with its own address and its own numbers.

Control which machines can join#

Auto-join sits on the Devices toolbar and is on by default. While it is on, any agent presenting the fleet token with a new name joins the fleet and appears in the list. Holding the token is what admits it.

Turn auto-join off and the fleet admits only names already on its roster. An unknown name is refused outright, and the agent stops instead of retrying. Machines already on the fleet keep running.

Use Create device to add a name before the machine exists. The row appears with no session, and you can write its grant straight away, so the machine is authorised before its first connection.

Disconnect or remove a device#

Disconnect cuts a device off now and stops it retrying. Its record, its address and its access all stay, so starting its agent again brings it back.

Remove device disconnects it, deletes the record and frees the name for reuse. While auto-join is on, the same machine rejoins the next time its agent connects, so turn auto-join off first to keep it out.

Fleet settings#

The Settings tab holds three groups. Changes apply when you select Save.

General carries the fleet Name, its Region, its Subdomain with a live availability check, an optional Custom Domain, and the fleet Token. Rotate issues a new token and the old one stops working straight away. Devices already connected keep serving, and each one needs the new token the next time it reconnects.

Network & Security carries two allowlists. Inbound IP Whitelist restricts the source addresses that may reach the fleet. Network IPs restricts the addresses your agents may connect from. Blank means anyone, and anywhere.

HTTP Protection carries Basic Authentication and Force HTTPS, both applying to HTTP devices.

There is no port field. Every device claims its own port.

Frequently asked questions#

How do I reach devices that cannot run any software?

Run the agent on one machine that can reach them over the local network, and give each piece of equipment its own endpoint in a config file. A PLC, a label printer or an IP camera then gets its own Localport address without anything being installed on it. Point each endpoint's url at the equipment's LAN address and port.

Can one fleet mix HTTP and TCP devices?

Yes. Protocol is chosen per device, so a fleet can carry an HTTP dashboard on one machine and SSH on another. A fleet does not carry TLS passthrough. Use tcp for a service holding its own certificate.

Does every device need its own token?

No. One token serves the whole fleet, and the --name flag is what separates the machines. Cutting one machine off is done by removing that device or by narrowing its grants, never by rotating a token every other machine shares.

How do I name a device?

Pass --name when you start the agent, or pick the machine from the roster in the dashboard's Connect panel. Names are lowercase letters, numbers and dashes, up to 48 characters, and unique on the fleet. Pick names that share a prefix, such as device1 and device2, so a single grant naming device* covers the ones you add later.

How do I run this on a machine with no terminal?

Add --noui, which prints plain log lines instead of the live display. That is the form to use inside systemd units, Docker containers and CI runners, where there is no interactive terminal and logs get collected.

Do the devices need a static IP, a port forward or a VPN?

No. Each agent makes an outbound connection and traffic arrives back down it. A machine behind NAT, behind carrier-grade NAT, or on a network whose firewall you do not control works the same as one with a public address.

What is the difference between a fleet and a fanout tunnel?

A fleet addresses machines individually: each device has its own URL and you choose which one to reach. A fanout tunnel does the opposite, copying every request to every connected machine at one shared URL. Fleets reach equipment. Fanout shares one webhook stream across a team.

What happens when two machines connect with the same name?

The second is refused and told the name is already in use. It keeps retrying. The usual cause is one agent restarting before its previous session has cleared, and that resolves on its own. Two genuinely different machines sharing a name keep failing with the same message until you rename one.

Can I put a fleet on my own domain?

Yes, using a wildcard custom domain. Each device is then served at its bare name under your domain, such as device1.devices.acme.com, and the fleet keeps its Localport address as well. Attach the domain when you create the fleet, or later from Settings. See Custom Domains.

How many devices can one fleet hold?

The ceiling comes from your plan, and the Devices tab tells you when you reach it. See pricing.