Fleets

Q: How do I open a port on a device?

Open the Devices tab, choose Edit from the device's menu, and add the port with its protocol, tcp or http . A device can hold up to 32 ports. The change reaches the machine within seconds, and removing a port closes the connections using it.

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, closing its ports or 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. Leave it off and the machine's hostname is used. 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 open the ports that machine should serve. Each machine gets an address of its own such as device1-example.eu.localport.dev, and callers reach any port behind it with localport access, holding a certificate your team trusts.

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.

You decide which ports each machine serves, in the dashboard. A device serves the list you give it and nothing else. The agent asks for no ports and takes no local address for them. It receives the list and applies it.

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 three 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.

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:

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 connect --token tok_YOUR_TOKEN --region eu --name device1

The device appears on the Devices tab as soon as the agent connects. There is no protocol and no local address on this command: the ports come next, from the dashboard.

On a server, add --noui:

localport connect --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. Leave --name off and the agent uses the machine's own hostname.

Open the ports a device serves#

A device serves nothing until you open a port on it. Open the Devices tab, choose Edit from a device's menu, and add each port:

Protocol is tcp or http. tcp carries anything, including a service holding its own certificate. http additionally counts requests and response codes in the access log.
Port is the port number on the machine, from 1 to 65535.

A device can hold up to 32 ports. The same list is on the create panel, so a machine that has not shipped yet can be filed with its ports already open.

Adding a port makes it reachable as soon as the machine acknowledges the change. Removing one stops new connections immediately and closes the connections already using it.

plc-01   tcp 502 · http 80
gw-01    tcp 22

The agent checks the list too. A connection for a port that is not on it is refused on the machine as well as at the edge.

Where each device answers#

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

device1-example.eu.localport.dev

That address carries no scheme and no port, because each port behind it carries its own protocol. It is not a link: a browser cannot open it, and nothing answers on it without a client certificate.

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

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.

Reach a device#

Every port is reached with localport access, which forwards it to a port on the machine you are sitting at:

localport access device1-example.eu.localport.dev -L 8080:80

Anything that then connects to localhost:8080 reaches port 80 on the device. Repeat -L for each port, and they all travel over one mutual-TLS connection:

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

The local port comes first, in the order ssh -L uses. Give one number instead of a pair and the system picks a local port and prints it.

For SSH, hand the connection straight to it instead of binding a port:

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

With no credential flag, the command uses the certificate the machine already holds and renews it in the background. Setup Keys sets that up once per machine, and Member Access signs a person in.

Run several devices from one machine#

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

version: 1
fleets:
  - token: ${LOCALPORT_TOKEN:?set LOCALPORT_TOKEN}
    devices:
      - name: device1
      - name: device2
        host: 192.168.10.22
      - name: device3
        host: 192.168.10.23

LOCALPORT_TOKEN=tok_YOUR_TOKEN localport connect --config localport.yaml

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

host is where that device's traffic goes on your network, and it defaults to the machine running the agent. Point it at a PLC, a label printer or an IP camera and that equipment gets its own Localport address without anything being installed on it. The ports stay in the dashboard, so host takes an address alone, with no scheme and no port.

Environment references

${LOCALPORT_TOKEN} fails with a clear error when the variable is unset. ${VAR:-default} supplies a default, and ${VAR:?message} fails with your own message. Use them to keep 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 ports it serves
Address	The device's own address, 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.

Access on an online device with ports open copies the localport access command for it, with one -L per port.

Each row's menu reaches the rest of Remote Access: Edit changes the name and the ports, 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, its ports 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.

A machine that joins this way serves no ports until you open some. It is on the roster, with an address and no way in.

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 open its ports and 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, its ports 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 two 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.

There is no port field and no password setting. A device's ports are on the device, and who may reach them is decided by certificates and grants.

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 device entry in a config file with a host pointing at its LAN address. A PLC, a label printer or an IP camera then gets its own Localport address without anything being installed on it. Open the ports in the dashboard as you would for any other device.

How do I open a port on a device?

Open the Devices tab, choose Edit from the device's menu, and add the port with its protocol, tcp or http. A device can hold up to 32 ports. The change reaches the machine within seconds, and removing a port closes the connections using it.

Can one device serve both HTTP and TCP?

Yes. Protocol is chosen per port, so one device can serve a web dashboard on port 80 as http and SSH on port 22 as tcp. Use tcp for a service that holds its own certificate. The stream is carried without being inspected.

Can I open a device in a browser?

No. A device has no public URL and answers nothing without a client certificate. Reach an HTTP port with localport access <device-address> -L 8080:80, then open http://localhost:8080 in the browser.

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, closing its ports or 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. Leave it off and the machine's hostname is used. 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 address and its own ports, 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 reached 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.