Setup Keys

Q: Can I provision this with Ansible, Terraform or a cloud-init script?

Yes. Pass the key through LOCALPORT_SETUP_TOKEN , or point LOCALPORT_SETUP_TOKEN_FILE at a file your secret manager writes. That is the shape systemd LoadCredential= and Docker secrets already give you. Add --wait so a machine that boots before its network is ready keeps retrying instead of failing the run.

Summary

A setup key lets one machine collect a certificate for one identity, without a dashboard session and without a password anyone has to store. You paste it once during provisioning, the machine keeps a private key that never leaves it, and from then on it renews itself.

Needs a fleet, which is on the Pro and Enterprise plans. See Fleets to create one.

What a setup key is#

A setup key authorises one machine to obtain a certificate for one identity. It is spent once and carries no access of its own. What that identity reaches is decided by the grants you write.

The machine it sets up is a caller, something that connects into a fleet: a deploy server, a monitoring collector, a jump box. Devices on the fleet itself authenticate with the fleet token instead. See Fleets.

The key is redeemed on the machine, which generates its own private key and sends only a certificate request. The key is spent as soon as it is redeemed.

Create a setup key#

Open Identities in the sidebar, then the Setup keys tab, then New setup key.

The first screen asks what you are setting up. Choose Server or machine. The other option, CI/CD pipeline, creates no secret and is covered in CI/CD with OIDC.

The form that follows asks for four things.

Name is how the key is listed here and in the audit log. It plays no part in authentication.
Identity is the name the certificate will carry, filled in from the Name. Grants are written against it and it survives every renewal, so choose it as carefully as a hostname. Lowercase letters, numbers and dashes, up to 48 characters.
Access ends is the last date this key may issue or renew anything. Never, 30 days, 90 days, 1 year, or a date you pick.
Allowed from is an optional list of IP addresses or CIDR ranges the key may be used from.

Certificate lifetime is not on the form. A machine set up this way gets 30 days and renews at two thirds of that.

Select Create setup key. The key is shown once, on the screen that creates it. Only its hash is stored, so it cannot be read back.

A setup key for a server. The identity fills itself in from the name, and the key is shown once.

Set the machine up#

Run this on the machine, once:

localport setup lps_YOUR_SETUP_KEY

For anything unattended, pass the key in the environment instead. An argument is visible in shell history and to ps for every account on the host:

LOCALPORT_SETUP_TOKEN=lps_YOUR_SETUP_KEY localport setup

LOCALPORT_SETUP_TOKEN_FILE names a file to read it from, the form systemd LoadCredential= and Docker secrets already provide.

The credential lands under ~/.localport/identity/, directories at 0700 and keys at 0600. Set LOCALPORT_HOME to put it elsewhere, which a service account with no home directory needs.

From then on the machine reaches devices with no credential flags at all:

localport access https://device1-example.eu.localport.dev -p 3001

A box that boots before its network

--wait keeps retrying an unreachable control plane, with backoff, for as long as you give it. A refused key is never retried at any setting and fails at once, so --wait 5m costs nothing on a bad key and saves a provisioning run on a slow one. Use --wait 0 in CI to make exactly one attempt.

What happens from then on#

The agent renews on its own, two thirds of the way through each certificate's life. The remaining third is retry budget, so a machine that is asleep, offline or on a flaky link has many attempts before anything expires.

Renewal carries no secret. The agent proves it still holds the current certificate's private key and asks for a replacement, so the setup key does not have to live on the machine after provisioning. Delete it from your provisioning system once the machine is up.

The previous certificate stays valid until its own expiry, so rollover overlaps and nothing drops.

A machine that is not permanently connected can renew from a timer instead:

localport identity renew

Renewal stops in any of these cases, each taking effect within one renewal cycle and none needing access to the machine:

The identity holds no grant anywhere in the team.
The certificate was revoked.
The setup key was revoked.
The key's Access ends date has passed.

Access ends is the one to set for contractors and pilot deployments. The machine works normally until that date, then stops renewing.

Pin a key to a network#

Allowed from takes IP addresses and CIDR ranges, comma-separated:

203.0.113.0/24, 198.51.100.7

It is checked at setup and at every renewal. A host that moves outside the range keeps working until its current certificate expires, then stops renewing. Use it for machines with a fixed egress address, and leave it blank for laptops.

The setup keys table#

The list shows active keys by default. Revoked keys are kept for the record and stay one filter away.

Column	Holds
Name	What you called it
Method	`Key` with the first characters of the key, or `CI/CD, no key` with the audience
Identity	The identity it issues for
Access ends	The date, or Never
Status	Active, Spent, Expired or Revoked

Spent and Revoked are different states. Spent means one machine collected its certificate. Revoked means an admin took the key out of service.

A key stays listed after it is spent, and its row menu opens View certificates filtered to the identity it issued for.

The setup keys list: what each key issues for, how far it runs, and where it is in its life.

Rotate a key without downtime#

Create the replacement first, provision the machine with it, then revoke the old key. Two active keys for one identity is expected during a rotation, and the form allows it.

Creating a key issues no certificate by itself. The machine's current credential keeps working and keeps renewing until the key behind it is revoked.

Edit or revoke#

Edit policy changes the Name, the Access ends date and the Allowed from list. The identity and the authentication method are fixed.

A narrowed pin or a shortened date takes effect at the next renewal. Certificates already issued keep their own expiry.

Revoke setup key stops the key issuing anything new and stops the certificates it issued from renewing. Certificates still inside their lifetime keep working until they expire. To cut a machine off immediately, revoke its certificate on the Certificates tab or remove its grant on the fleet.

The record is kept after revocation, so what the key issued stays attributable.

Creating, editing and revoking setup keys needs the admin or owner role.

Frequently asked questions#

What is a setup key?

A single-use string that lets one machine collect a client certificate for one identity, without a dashboard login and without a stored password. The machine generates its own private key, sends a certificate request, and the setup key is spent. Everything after that is renewal, which needs no secret at all.

Can I use one setup key for many machines?

No. A key is spent by the first machine that redeems it. Create one key per machine, which is also what makes the audit trail useful, since each key records which identity it issued for and when it was used.

I lost the setup key before using it. What now?

Create another one. The key is shown once on the screen that creates it and only its hash is stored, so there is nothing to recover. Revoke the lost key afterwards so it cannot be redeemed by whoever finds it.

How does the certificate renew?

The agent renews two thirds of the way through each 30-day certificate, proving it still holds the current certificate's private key. No setup key, API key or password stays on the machine. The previous certificate remains valid until its own expiry, so the rollover overlaps.

What does the Access ends date actually stop?

It stops the key issuing or renewing anything after that date. Certificates already issued keep their own expiry and keep working until they reach it, a machine goes quiet within a renewal cycle of the date, not at midnight on it. To cut it off at a precise moment, revoke the certificate.

Can I pin a setup key to an IP address?

Yes, with Allowed from. Setup and every renewal are refused from anywhere else, so a machine whose egress address changes stops renewing and its certificate lapses. Use it for hosts with a fixed egress address, and leave it blank for laptops and anything behind a changing network.

What is the difference between revoking a key and revoking a certificate?

Revoking the key stops new certificates being obtained and stops the existing one renewing, while that certificate keeps working until it expires. Revoking the certificate cuts the machine off now, closing its open connections on every fleet. Use the key for planned off-boarding and the certificate for an incident.

Does a setup key give the machine access to anything?

No. It produces an identity, and an identity with no grant reaches nothing. Write the grant on each fleet the machine should reach, either while creating the key or later from the fleet's Access tab. A key whose identity holds no grant anywhere also stops renewing after its first certificate.

Do I set up the machines on the fleet this way?

No. Machines that are on a fleet connect with the fleet token and --name, and they need no certificate of their own. A setup key is for the other side: whatever reaches into the fleet, such as a deploy server, a monitoring collector or a jump box. See Fleets.

Can I provision this with Ansible, Terraform or a cloud-init script?

Yes. Pass the key through LOCALPORT_SETUP_TOKEN, or point LOCALPORT_SETUP_TOKEN_FILE at a file your secret manager writes. That is the shape systemd LoadCredential= and Docker secrets already give you. Add --wait so a machine that boots before its network is ready keeps retrying instead of failing the run.