Remote Access

Q: Which protocols can a fleet carry?

Anything built on TCP, chosen per port. Open a port as tcp for SSH, Postgres, MQTT, VNC or a service holding its own TLS certificate, and as http for a web service whose requests and response codes you want counted in the access log. One device can serve both.

Summary

Identity-based access to machines you have already deployed. Group them into a fleet, open the ports each one serves, and grant each caller the devices it may reach. Callers forward those ports to their own machine with localport access, holding a certificate your team trusts. Available on the Pro and Enterprise plans, see pricing.

How Remote Access works#

Remote Access gives your team identity-based access to devices, and to the services running on them, wherever they sit behind NAT or a firewall. No public IP address, no port forwarding, no inbound firewall rule.

A fleet holds the devices and is private from the moment it exists. Each device is one machine with a name of its own, and it serves the ports you open on it in the dashboard. Access grants decide which identities reach which devices, and the credential each caller holds decides how long that access lasts.

Callers reach a port by forwarding it. localport access gw-01-plant.eu.localport.dev -L 5020:502 listens on port 5020 of the machine you are sitting at and carries every connection to port 502 on the device. All of a device's forwards travel over one mutual-TLS connection, and each local connection becomes its own stream inside it.

The connection to the device is checked when it opens, and each port forwarded through it is checked again when it is used:

The client certificate chains to your team's authority, or to one you registered.
The certificate has not expired and has not been revoked.
A grant covers the device being reached.
The port is open on that device.

A connection failing any of these is refused and recorded. Nothing on a fleet is reachable by address alone.

Set up Remote Access#

Step 1: Create a fleet and connect your machines#

Create the fleet in the dashboard, then copy the command it hands back and run it on each machine. Every machine that connects joins the fleet as a device with an address of its own, such as device1-example.eu.localport.dev.

localport connect --token tok_YOUR_TOKEN --region eu --name device1

One token serves the whole fleet, and --name is what separates the machines. The command names no protocol and no local address, because a device serves the ports you open on it next.

Create the fleet, copy the command it builds, and each machine appears on the Devices tab as it connects.

Detailed guide: Fleets

Step 2: Open the ports each device serves#

A device that has joined the fleet serves nothing yet. On the Devices tab, choose Edit from a device's menu and add each port it should serve: a Port number and a Protocol, tcp or http. A device can hold up to 32 ports.

tcp carries anything built on TCP, including a service holding its own TLS certificate. http carries the same traffic and additionally counts requests and response classes in the access log.

The agent takes the list as given. It asks for no ports of its own, so a machine cannot expose something you did not open. Adding a port makes it reachable as soon as the machine acknowledges the change, and removing one stops new connections at once and closes those already running on it.

Step 3: Control who can reach each device#

A fleet is private by default. Your devices are online and reachable by nobody until you say who gets in. On the fleet's Access tab you choose the identity type, choose the subject, then choose the devices it reaches. Grants union together and there are no deny rules, they name an identity instead of a certificate so they survive every renewal, and a change applies to connections that are already open.

Give access: choose the identity type, choose the subject, then choose which devices it reaches.

Every grant answers two questions, and the panel asks them in that order. Who is the subject, and it comes in three kinds.

Subject	Covers	Use it for
Role	Owners, Admins or Developers	Giving a whole group access at once, such as every Developer
Member	Individual member on team	Access for an individual, on top of whatever their role already gives them
Machine	Individual machine identity	Servers, monitoring collectors, CI/CD jobs and downloaded certificates

What it reaches is the second question. Devices are named directly, either one at a time or by a prefix that covers a whole series.

Target	Reaches
`*`	Every device on the fleet, now and later
`device*`	Every device whose name starts with `device`, now and later
`device1`	Exactly that device

A trailing star is the only wildcard, and it covers devices you deploy afterwards. Anything the grant does not name is refused. A grant covers a device and every port open on it, so a port you should not hand out belongs on a device of its own.

Detailed guide: Grants and Access

Step 4: Connect#

Run localport access on the machine that needs to reach the device. Each -L opens a local port and forwards it, so the remote service is available at localhost on the port you chose. Connect your tools to that port exactly as you would to anything running on the machine itself.

The local port comes first, in the order ssh -L uses, and -L repeats for each port you want.

Signing in issues a certificate to the machine you run the command on. It is valid for 8 hours, and you sign in again once it expires.

localport login
localport access device1-example.eu.localport.dev -L 3001:80

The first command prints a code, you approve it in a browser, and the certificate is stored on that machine. The second forwards port 80 on the device to localhost:3001, so your browser or client connects there. The CLI reference covers listing, renewing and removing stored credentials.

Connect as yourself. The sheet takes the code localport login printed.

A setup key is spent once, during provisioning. The agent then holds a certificate it renews on its own, for as long as the key's Access ends date allows.

localport setup lps_YOUR_SETUP_KEY
localport access device1-example.eu.localport.dev -L 3001:80 -L 5020:502

The first command redeems the key and stores the credential, after which no long-lived secret remains on the machine. Renewal runs on its own. The second forwards two of the device's ports, both over one connection.

Connect with a machine credential. Pick the identity, and the command names it.

The job authenticates with the token its own platform mints and receives a 15-minute certificate held in memory. Nothing is stored in the repository, the CI secret store or the runner.

localport access device2-example.eu.localport.dev \
  --audience lpa_YOUR_AUDIENCE -L 2222:22

The certificate is requested when the step starts and is gone when the job ends. The command forwards port 22 on the device to localhost:2222, so the rest of the job connects there.

Connect from a pipeline. The audience names the binding, and no secret is stored.

For SSH there is no need to bind a local port at all. --stdio hands one connection straight to the client:

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

Identities and credentials#

Every caller authenticates with a client certificate. How it obtains one depends on what the caller is.

Identity	Obtains a certificate with	Detailed guide
Member, a person on your team	`localport login`. Short-lived, re-issued by signing in again	Member Access
Machine, a long-running server, gateway or appliance	A single-use setup key, after which the agent renews itself	Setup Keys
CI/CD pipeline, an ephemeral build or deploy job	Its own platform's OIDC token. No secret is stored anywhere	CI/CD with OIDC
Application or appliance that cannot run the agent	A certificate file issued from the dashboard, PEM or PKCS#12	Certificates

We hold no private keys. Every issuance path is a certificate request: the key pair is generated where the certificate will be used and the private half never leaves it. The dashboard download is no exception, since the browser generates that key and uploads only the request.

Access logging#

Every access session is recorded, allowed or refused, one entry per device port. Each entry names the identity that connected, the device and port it reached, the address it came from, how long it lasted and how much data crossed. A session appears within seconds of opening and stays marked Active until it closes. On an http port the entry also carries the number of requests and how many answered 2xx, 3xx, 4xx and 5xx. A refusal records why it was refused.

Traffic is never inspected. Request paths, headers and bodies are not captured anywhere, so you get a full audit trail of who reached what, and no copy of what they sent.

The access log: one entry per session and port, live sessions marked Active.

Detailed guide: Access Log

Certificate authorities#

Localport runs a managed certificate authority for your team, created with your first fleet. It signs every credential above, and it needs no configuration.

You can also bring your own certificate authority. You register the public chain, Localport verifies callers against it, and your signing key never reaches us. A registered authority carries three requirements:

A trust domain it speaks for, so its identities are namespaced as acme.corp/build-agent and cannot collide with names in your team.
A CRL URL over HTTPS, polled every 15 minutes, so your revocations take effect here.
An identity source, either a SPIFFE URI SAN or the certificate's common name.

A registered authority verifies but cannot issue, since we hold no key for it. Teams commonly run both.

Detailed guide: Certificate Authorities

Revoking access#

Each of these closes the connections it affects immediately, not at the end of the session and not on the next attempt.

Action	Scope
Narrow or remove a grant	That subject, on that fleet
Close a port on a device	That port, for everyone using it
Revoke a certificate	That certificate, on every fleet in the team
Remove a device	That device, and its name becomes free to reuse
Remove a certificate authority	Everything that chained to it
Remove a team member	Their individual grants, their sign-in certificates and their sessions

Narrowing counts as revoking. Tightening a grant from device* to device1 cuts every other device it used to cover.

Frequently asked questions#

What is mutual TLS (mTLS)?

Mutual TLS is ordinary TLS with the identity check running in both directions. In a normal HTTPS connection the server proves who it is and the client stays anonymous. With mutual TLS the client presents a certificate as well, and the server refuses the connection when it does not recognise it. Every Localport fleet works this way.

Do I need to change my application?

No. The Localport agent runs beside your service and forwards a local port to it. Your application sees an ordinary local connection and never handles a certificate itself. Every check has already run by the time a byte reaches it.

Does holding a certificate mean someone has access?

No. A certificate proves identity and nothing else. Until a grant on a fleet names that identity, it reaches nothing there. Grants are written per fleet, so a certificate that reaches one fleet reaches another only once you say so.

Can I give someone one port on a device but not another?

Not within one device. A grant covers a device and every port open on it. Where two services on one machine need different audiences, run that machine as two devices, each with its own name and its own ports, and grant them separately. A config file makes that one process: see Configuration.

Can I protect a single service without running a whole fleet?

Yes. Create a fleet and connect one device to it, with one port open. A fleet of one is supported and behaves like any other, and you can add a second device later without changing anything a caller already holds.

What happens to connections that are already open when I remove access?

They close immediately. Narrowing a grant, closing a port, revoking a certificate, removing a device and removing a certificate authority all cut the connections they affect. Nothing is left running until it finishes on its own.

Can I use my own certificate authority?

Yes. Register the public chain and Localport verifies every caller against it. Your signing key never reaches us, and you keep issuing device certificates with your own tooling. A registered authority also supplies a revocation list URL, which Localport polls so your revocations take effect here too. See Certificate Authorities.

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

No. The agent makes an outbound connection to Localport 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.

Which protocols can a fleet carry?

Anything built on TCP, chosen per port. Open a port as tcp for SSH, Postgres, MQTT, VNC or a service holding its own TLS certificate, and as http for a web service whose requests and response codes you want counted in the access log. One device can serve both.

Can I open a device in a browser?

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

Can someone outside my team be given access?

Yes, through their organisation's own certificate authority. Register it, and the identities it signs resolve inside a namespace of their own, so a partner's corp.example/build-agent can never collide with a name in your team. You write grants for those identities exactly as you would for your own.

Who can change access?

Writing or removing a grant needs the admin or owner role. Members with the developer role can see who has access without changing it. Certificates, setup keys and the access log also need admin or owner.