Remote Access
Identity-based access control for machines you have deployed. Grant each person, server or pipeline access to one device, a group, or nothing at all.
Summary
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 is where you manage those devices, and it is private by default. Access grants control who reaches which devices, and the credential each caller holds controls how long that access lasts.
It runs on mutual TLS (mTLS). Every caller presents a client certificate, the certificate carries a verified identity, and the connection is refused in the TLS handshake unless a grant covers the device being reached.
Set up Remote Access#
Step 1: Create a fleet#
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 a public address of its own.
The fleet is where you manage all of them together: what is online, what each one is serving, what it is doing right now, and who is allowed to reach it. A fleet carries HTTP and TCP, so it covers web services, APIs, SSH, databases, MQTT and anything else built on TCP.
Detailed guide: Fleets
Step 2: 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.
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.
Detailed guide: Grants and Access
Step 3: Connect#
Run localport access on the machine that needs to reach the device. It 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.
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 https://device1-example.eu.localport.dev -p 3001The first command prints a code, you approve it in a browser, and the certificate is stored on that machine. The second forwards the device to localhost:3001, so your browser or client connects there. The CLI reference covers listing, renewing and removing stored credentials.
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 https://device1-example.eu.localport.dev -p 3001The 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 the device to localhost:3001.
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 tcp://device2-example.eu.localport.dev:22 \
--audience lpa_YOUR_AUDIENCE -p 2222The certificate is requested when the step starts and is gone when the job ends. The command forwards the device to localhost:2222, so the rest of the job connects there.
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 connection to a device is recorded, allowed or refused. Each entry names the identity that connected, the device it reached, the address it came from, how long it lasted and how much data crossed. 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.
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-agentand 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 |
| 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 protect a single service without running a whole fleet?
Yes. Create a fleet and connect one device to it. 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, revoking a certificate, removing a device and removing a certificate authority all cut the sessions they affect, on every protocol. 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?
HTTP and TCP. That covers web services, APIs, SSH, Postgres and other databases, MQTT brokers, VNC and anything else that speaks TCP. A service holding its own TLS certificate is registered as tcp, and its own TLS runs end to end inside the connection.
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.
What to read next#
- Fleets - create one and connect your machines
- Grants and Access - decide who reaches which devices
- Certificates - the four ways a caller gets one
- Setup Keys - set up a server or appliance once
- Access Log - who reached what, and when
- CLI - every flag
localport accesstakes