Activation and license#
A new installation asks for two things before anyone can sign in: an activation, and a way to sign in. It then runs in evaluation mode for 30 days, until an installation owner enters a license key.
Activation is local. It needs no connection to a Lens service, and the license key is checked inside the installation.
Activate#
The chart generates an activation code into a Secret and keeps it across upgrades. For a release named lens-agents, the Secret is lens-agents-activation; the install notes print the exact command for yours. Only people who can read the release's Secrets have it, so a stranger who finds the URL first cannot activate the installation.
-
Read the code:
kubectl -n <namespace> get secret lens-agents-activation \ -o jsonpath='{.data.activationCode}' | base64 -d; echoThe install notes and the Activate screen print the same command for your release.
-
Activate with your name, company, work email, and the code:
Open
config.publicUrlin a browser, fill in the Activate screen, and submit it.nexusctl installation activate --server https://agents.example.com \ --code <activation-code> --name "Jane Doe" --company "Acme Inc." --email jane@acme.comcurl -fsS -X POST https://agents.example.com/v1/installation/activation \ -H 'Content-Type: application/json' \ -d '{"activationCode": "<activation-code>", "name": "Jane Doe", "company": "Acme Inc.", "email": "jane@acme.com"}'
Activation creates the first organization, named after the company, when the installation has none. The person whose email activated the installation becomes its admin when they first sign in. Everyone else joins by invitation. When config.ownerEmails is set, the email must be one of the owners.
GitOps
Argo CD, helm template, and other tools that render without cluster access generate a new code on every render. Put your own code, at least 16 characters, in a Secret and set activation.code.existingSecret.
Activate from Helm values#
Set all three values, and the installation activates itself when it starts. The Activate screen is then skipped: who sets the values runs the installation. Lens ID sign-in still asks for the activation code.
helm upgrade lens-agents oci://ghcr.io/lensapp/lens-agents \
--reset-then-reuse-values \
--set activation.activator.name="Jane Doe" \
--set activation.activator.company="Acme Inc." \
--set activation.activator.email=jane@acme.com
The chart refuses to render only some of the three. The platform refuses to start with an email that is not valid, or that is not in config.ownerEmails when that is set. An installation that is already activated ignores the values. The chart puts them in the release's ConfigMap, where anyone who can read ConfigMaps in the namespace can see them.
Choose how people sign in#
With oidc.clientId set, the installation already has an identity provider, and people sign in after the activation. See SSO.
Without it, the setup screen offers two ways:
- Your own identity provider. Set
oidc.issuer,oidc.jwksUri, andoidc.clientId, and upgrade the release. The screen prints the redirect URIs to register. -
Lens ID. Choose Use Lens ID as OIDC, open Lens Cloud, and approve the code it shows with your Lens ID. Lens Cloud then registers a sign-in client for this installation. Sign up for a Lens ID at app.k8slens.dev.
From the CLI:
nexusctl installation use-lens-id --server https://agents.example.com --code <activation-code>
The Lens ID that approves the code owns the Lens Cloud registration. Prefer a long-lived service account over a personal account, so the installation does not depend on one person.
Check the status#
nexusctl installation status --server https://agents.example.com
curl -fsS https://agents.example.com/v1/installation
{
"activated": true,
"signInConfigured": true,
"activationCodeHint": null
}
The endpoint needs no authentication — it is what the setup screen itself polls.
Evaluation#
The evaluation lasts 30 days from the activation, with nothing limited. The Evaluation card in the sidebar shows the days left.
When the period ends without a valid license key, the web UI shows only an Evaluation ended screen. An installation owner can enter a key there, or continue the evaluation for another 30 days. Other people see that they must ask an owner. nexusctl, MCP clients, the REST API, and running sandboxes continue to work.
An expired or revoked key counts as no key. When a key expires after the evaluation period, the web UI shows License expired at once.
Enter a license key#
A license key is bound to the name it was issued to. Enter the name exactly as it came with the key; letter case and spacing do not matter. Contact us for a key.
An installation owner enters it on the License page — choose the Evaluation card in the sidebar — or with the CLI or the API, signed in as a person. An API token cannot enter it. When config.ownerEmails is empty, any signed-in person can enter it.
nexusctl installation license --owner "Acme Inc." <license-key>
Without a key, nexusctl installation license shows the license.
curl -fsS -X PUT https://agents.example.com/v1/installation/license \
-H "Authorization: Bearer $USER_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"owner": "Acme Inc.", "key": "<license-key>"}'
Any signed-in person can see the license. The unauthenticated status endpoint does not show it.
Give the key with Helm values#
Put the key in a Secret and name the owner:
kubectl create secret generic lens-agents-license \
--from-literal=LICENSE_KEY=<license-key>
helm upgrade lens-agents oci://ghcr.io/lensapp/lens-agents \
--reset-then-reuse-values \
--set license.owner="Acme Inc." \
--set license.existingSecret=lens-agents-license
The platform stores the key when it starts on an activated installation, and it replaces a key entered on the License page. It refuses to start with a key that is not valid for the owner. An expired or revoked key does not stop a start; the platform logs a warning at each start instead.
What activation sends#
Nothing, when product telemetry is off. When it is on, the name, company, and email from the activation go with the installation's usage data in one event.
Lens ID sign-in connects to Lens Cloud at activation.apiUrl. It registers the installation's sign-in client once, with the installation ID, config.publicUrl, the platform version, and the Lens ID username. It renews that registration about once a week, with the platform version. People sign in through the Lens Cloud realm. With your own identity provider, none of this happens. Data sovereignty has the complete picture of what leaves your cluster.
Values#
| Value | Default | Purpose |
|---|---|---|
activation.code.existingSecret |
(empty) | Your own Secret holding the activation code. Empty generates one: lens-agents-activation for a release named lens-agents. |
activation.code.key |
activationCode |
Key of the code in that Secret. |
activation.activator.name / .company / .email |
(empty) | All three set: the installation activates itself when it starts. |
activation.apiUrl |
https://api.k8slens.dev |
The Lens Cloud API that Lens ID sign-in registers with. |
activation.bootstrapClientId |
(empty: lens-agents-bootstrap) |
The Lens Cloud client that Lens ID registration starts with. |
license.owner |
(empty) | The name the license key was issued to. |
license.existingSecret |
(empty) | Secret holding the license key. |
license.existingSecretKey |
LICENSE_KEY |
Key in that Secret. |
license.key |
(empty) | The license key itself. Prefer existingSecret: this puts the key in the release's values. |
Upgrading from Hub enrollment#
Before 0.36.0, an installation enrolled with Lens Hub. On the upgrade, the platform forgets the enrollment and keeps everything else: users, organizations, data, and the Lens ID sign-in client that the enrollment provisioned.
The web UI then shows the Activate screen once. Activate with the code from the activation Secret, or set the activation.activator values. People sign in as before. The 30-day evaluation counts from the activation. nexusctl, MCP clients, and the REST API continue to work before the activation.
Upgrade with --reset-then-reuse-values, as the commands on this site do. --reuse-values keeps the old chart's values and fails on the new activation values. Remove the hub values and oidc.useExternalProvider from your values; they are no longer read.
Air-gapped installations are configured per environment. Talk to us.
Related#
- Install on Kubernetes — the install this activates
- SSO — authenticate users against your own IdP
- Organizations and projects — installation owners, and what to create once you are in