Skip to content

Activation#

A fresh install boots unactivated. It has no OAuth client of its own yet, so it cannot complete a login, and it shows an activation screen instead of the admin UI.

Activation runs an OAuth device flow against Lens Cloud once. It registers a per-install OAuth client and a license for this deployment. After that, Lens ID login works and the install runs on its own.

Activate#

  1. Open config.publicUrl in a browser.
  2. Click Activate this installation.
  3. Follow the device-flow prompt and sign in with your Lens ID.
  4. Approve the consent screen.
nexusctl installation activate --server https://agents.example.com

The command prints a verification URL and code. Open the URL, sign in with your Lens ID, and approve.

Either path ends the same way. The approval itself authorizes the install — there is no separate activation key to store or rotate.

Check the result at any time:

curl -fsS https://agents.example.com/v1/installation

{
  "activated": true,
  "licenseValid": true,
  "status": "activated",
  "registeredByEmail": "platform@example.com",
  "registeredAt": "2026-08-01T09:14:22Z",
  "plan": "Lens Agents Trial"
}

The endpoint needs no authentication — it is what the activation screen itself polls.

nexusctl installation status --server https://agents.example.com

The activating account owns the install#

The Lens ID that approves activation becomes the owner of the installation and its first organization administrator.

Use a long-lived service account Lens ID, not an individual's personal account. An install owned by someone who leaves the company is an install whose ownership has to be recovered.

What activation sends#

Activation registers this deployment with Lens Cloud: it posts an installation record to {activation.apiUrl}/users/{username}/installations and receives back an OAuth client and a license JWT.

Licenses are verified offline against a public key bundled in the platform image, so the install does not call home per request and keeps working if Lens Cloud is unreachable. Partway through a licence's lifetime it fetches a re-signed one and reports its platform version; that call is fail-soft too.

Nothing about your agents, sandboxes, policies, credentials, or audit trail is part of the activation exchange. Separately from activation, a default install does emit product telemetry — read that page for the full event list, and for how to point it at your own collector or turn it off. Data sovereignty has the complete picture of what leaves your cluster.

Values#

Value Default Purpose
oidc.clientId (empty) Empty means self-activate. Set it only for a pre-provisioned deployment that should skip activation.
oidc.issuer Lens Cloud realm OIDC issuer for end-user login.
oidc.jwksUri Lens Cloud realm JWKS endpoint for verifying login tokens.
activation.apiUrl https://api.k8slens.dev Lens Cloud API the install registers against.
activation.bootstrapClientId (empty) Overrides the bootstrap client id used for the device flow.

Bring your own identity provider#

oidc.issuer and oidc.jwksUri default to Lens Cloud, which is what makes Lens ID login work out of the box. Point them at your own OIDC provider to authenticate users against your directory instead. See SSO.

Air-gapped installs, pre-provisioned OAuth clients, and deployments that must never reach Lens Cloud are configured per environment. Talk to us.