Set Up Remote Access to a Device Fleet

What you will have at the end#

A fleet named Retail holds a set of in-store kiosks. Each kiosk runs the Localport agent as a service and serves one port, SSH on 22. Every Developer on your team reaches any kiosk with ssh kiosk-0142. A deploy server reaches them with a machine identity of its own. Every connection appears in the access log with the identity that made it.

The guide uses kiosks and SSH as the running example. The same steps apply to gateways, chargers, signage players and servers, and to any TCP service they run.

Before you start#

You need:

• A team on the Pro, Business or Enterprise plan. Fleets are not available on other plans.
• The owner or admin role on that team. Creating a fleet and writing access grants need one of them.
• Linux machines with systemd and an SSH server. Install the agent on each one with Installation.
• The Localport agent on your own computer, to connect to the devices.

How Remote Access reaches a device#

The agent on each kiosk opens outbound connections to Localport on port 443. Nothing on the store's network accepts an inbound connection, so the kiosk needs no public IP address, no port forwarding and no inbound firewall rule. The network only has to allow outbound connections on port 443. It works behind NAT, carrier-grade NAT and networks you do not administer.

A person or machine reaches a kiosk with localport access, which presents a client certificate stored on their computer. Each connection is checked when it opens and again for each port it uses:

• The certificate chains to your team's certificate authority, has not expired and has not been revoked.
• An access grant on the fleet names that identity and covers the device.
• The port is allowed on the device.

A connection failing any check is refused. A refusal for a missing grant, a revoked certificate or a port that is not allowed is recorded in the access log. A certificate that has expired or was not issued by your team is rejected during the TLS handshake and is not logged. A fleet has no public address, so nothing on it is reachable by address alone. Detailed explanation: Remote Access.

Plan your device names#

Decide the naming scheme before the first device exists. A device's name is its address and the name every grant refers to, and it cannot be edited.

• Give each type of device its own prefix. kiosk-0141, kiosk-0142 and so on. A grant for kiosk-* then covers every kiosk, including the ones you deploy next year.
• Keep different audiences on different prefixes. A grant reaches every port allowed on a device. Machines that different people should reach belong under different prefixes, or on a different fleet.
• Use lowercase letters, digits and dashes. A device name is up to 48 characters, with no dash at the start or end. A long fleet subdomain shortens that limit, because the device name and the subdomain together form one DNS label of at most 63 characters.

Set up the fleet#

Step 1: Create the fleet and its first device#

In the dashboard, go to Fleets and click Create fleet. Enter the Name Retail, choose a Region, and click Create Fleet.

The sheet moves to Create device & Connect. Enter the first device name, kiosk-0141, add port 22 with protocol TCP, and click Create device. The sheet then shows the command for that device.

The fleet starts with a generated address. To give it a readable one, open the fleet's Settings and enter retail-kiosks in Subdomain, then save. Do this before any agent connects. Each device's address is its name joined to this subdomain:

kiosk-0141-retail-kiosks.eu.localport.dev

The fleet's Token is one credential for every device in it, and the device name says which device a machine connects as. Anyone holding the token can connect as any device on the roster, so treat it like a password. If it leaks, click Rotate next to the Token field in the fleet's Settings and update each device. Detailed guide: Fleets.

Step 2: Turn auto-join off#

Open the fleet's Devices tab and switch Auto-join off. The dashboard confirms: "New devices are refused. Devices already here keep running."

With auto-join on, a machine that connects with the fleet token and an unknown name becomes a new device. With it off, the roster in the dashboard is the complete list of devices that may connect. A copied token cannot add a machine you did not create.

Step 3: Add the remaining devices#

On the Devices tab, click Create device for each kiosk. Enter its name, add port 22 as TCP, and click Create device.

A device serves only the ports allowed on it in the dashboard, up to 32. Allowing a port makes it reachable within seconds. Removing one closes the connections using it. Edit in a device's menu changes the list at any time.

Step 4: Run the agent as a service on each device#

The agent ships a hardened systemd unit, deploy/localport.service. It runs as an unprivileged user and reads the token from a file that only the service can read. Copy it to the kiosk and change its ExecStart= line to the device form:

ExecStart=localport connect --region eu --name kiosk-0142 --allow-ports 22

Then install the token and start the service:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin localport
sudo install -d -m 0700 -o localport -g localport /etc/localport
printf '%s' 'tok_YOUR_FLEET_TOKEN' | sudo tee /etc/localport/token >/dev/null
sudo chmod 0600 /etc/localport/token
sudo cp localport.service /etc/systemd/system/
sudo systemctl enable --now localport

The flags in ExecStart=:

• --name kiosk-0142 is the device this machine connects as. It must match a device on the roster, since auto-join is off. Without --name, the agent uses the machine's hostname.
• --region eu is the region you chose for the fleet.
• --allow-ports 22 is an optional ceiling set on the machine itself. The agent serves only port 22, whatever is allowed in the dashboard. A port allowed in the dashboard outside this list stays unreachable, and the Devices tab marks it as blocked by the device.

The token never appears in ExecStart=, where ps and systemctl show would show it to every local account. The agent writes plain log lines under systemd. Check it with journalctl -u localport -f. The kiosk appears online on the Devices tab within seconds. Detailed guide: Installation.

Give your team access#

Step 5: Grant Developers every kiosk#

The fleet is private from the moment it exists. Online devices reach nobody until a grant names who may connect.

Open the fleet's Access tab and click Give access. The sheet asks three things in order:

• Type: choose Role.
• Who: choose Developers.
• Access: leave All devices off, type kiosk-* in the search field and press Enter to add it as a pattern.

Click Give access to Developers. Every member holding the Developer role, including people who join later, now reaches every device whose name starts with kiosk-. A role grant covers that role only. Owners and admins who also connect need a grant of their own, for the Owners or Admins role or for themselves as a Member.

The Access tab lists every grant on the fleet:

Grants add together and there are no deny rules. A change applies to connections that are already open. Detailed guide: Grants and Access.

Step 6: Connect over SSH as a member#

A member proves who they are by signing in from the terminal. On their own computer:

localport login

The agent prints a code and a link. The member opens the link, signs in to the dashboard, chooses the team if asked, checks the code matches the one in the terminal and clicks Sign in. The agent receives a certificate valid for 8 hours. Signing in again issues a new one.

To make ssh kiosk-0142 work directly, add one entry to ~/.ssh/config:

Host kiosk-*
  User ops
  ProxyCommand localport access %h-retail-kiosks.eu.localport.dev --stdio 22

%h is the name typed after ssh, so ssh kiosk-0142 reaches kiosk-0142-retail-kiosks.eu.localport.dev. --stdio 22 carries the SSH connection over the agent's standard input and output, so no local port is opened. SSH host keys and user authentication work as they do on a local network.

ssh kiosk-0142

For a tool other than SSH, forward a local port instead: localport access kiosk-0142-retail-kiosks.eu.localport.dev -L 2222:22 listens on localhost:2222. Detailed guide: Member Access.

Step 7: Give a deploy server its own identity#

A server that runs unattended uses a machine identity in place of a person's sign-in. It obtains its certificate with a setup key, once.

Go to Identities, open the Setup keys tab and click Create setup key. Choose Server or machine, then fill in:

• Name: Deploy server, a label for the dashboard.
• Identity: deploy-server. Grants are written against this name.
• Access ends: the last date the key can issue or renew a certificate, or Never.

Copy the key. It is shown once. Click Choose what it can reach, pick the Retail fleet, add the pattern kiosk-*, and click Grant access to deploy-server. A key whose identity holds no grant stops renewing after its first certificate.

On the deploy server, redeem the key:

localport setup lps_YOUR_SETUP_KEY

The key is spent. The private key was generated on the server and never left it. The certificate lasts 30 days and the agent renews it at two thirds of that time, for as long as Access ends allows. The server then uses the same ~/.ssh/config entry as a member. Detailed guide: Setup Keys.

Run the fleet day to day#

Step 8: Remove someone's access#

When a person leaves, remove them on the team's Members page with Remove member. Their sign-in certificates are revoked, their individual grants are deleted, and role grants stop covering them. Their open connections close.

To take one person off this fleet without removing them from the team, change their role, or narrow the grant that covers them on the Access tab. Narrowing a grant closes the connections it no longer covers.

Step 9: Decommission a device#

When a kiosk is retired, open its menu on the Devices tab and choose Remove device. The device is disconnected, its agent stops reconnecting, and its record is deleted. Its name can be reused.

Auto-join is off, so the machine stays out even if a supervisor such as systemd restarts its agent. With auto-join on, a restarted agent joins again as a new device.

Disconnect in the same menu cuts a device off and keeps its record, address and grants. Starting its agent again brings it back.

Step 10: Review who connected#

Access log in the team's sidebar lists every access session, allowed or refused, one entry per device port. Each entry names the identity, the device and port, the source address, how long it lasted and how much data crossed. A refusal records its reason.

Filter by outcome, port, source address and time range, then click Export CSV to download the filtered entries for a security review. The access log is readable by team admins and the owner. Detailed guide: Access Log.

How access is controlled#

• No inbound ports. Devices connect outward on port 443. A store's network needs no inbound rule and exposes nothing.
• Private by default. A fleet has no public address. A device is reachable only with a valid client certificate and a grant that covers it.
• Identity is a certificate. Members, machines and pipelines each hold a client certificate. Every key pair is generated on the machine that uses it, and its private key never leaves that machine. Localport signs the certificate from a request the machine creates.
• Access is per identity, per device. Grants name a role, a member or a machine, and the devices it reaches. Grants are written by admins and the owner.
• Revocation is immediate. Narrowing a grant, removing a port, revoking a certificate, removing a device and removing a member close the connections they affect.
• Sessions are recorded. The access log records who reached which device and port, from where and for how long, and each refusal for a missing grant, a revoked certificate or a closed port. Traffic content is not logged.
• The device can set its own limit. --allow-ports on the machine caps what it serves, independent of the dashboard.

Limitations#

• A grant covers every port allowed on a device. To give two audiences different ports on one machine, run it as two devices with different names.
• A browser cannot open a device directly. Forward the port first with localport access <device-address> -L 8080:80, then open http://localhost:8080.
• Fleets carry TCP. Each port is tcp or http. UDP is not carried.
• Remote Access reaches devices. It does not manage them. It does not push software updates, collect device metrics or track location. Run those over the access it gives you.

Frequently asked questions#

What to read next#

• SSH into Devices Behind NAT, CGNAT or Firewalls. The SSH workflow in depth: config, file copies, session lifetime and errors.
• Remote Access. How the product works and every credential type.
• Fleets. Devices, ports and fleet settings in detail.
• Grants and Access. Roles, members, machines and device patterns.
• Member Access. Signing in with localport login.
• Setup Keys. Credentials for unattended machines.
• Access Log. Filtering and exporting connection records.