---
title: Lenso Console
description: Connect an exact System, load Module Surfaces, and inspect direct operational status.
---

Lenso Console is the independently installed operator-facing System Plane for
one Lenso System. Its Shell, API, Worker, Auth domain, Registry, and Store run
separately from the business Services it observes.

Console has a deliberately narrow role: connect, report status, load exact
Module Surfaces, and invoke typed target-owned operations. It does not create,
deploy, adopt, delete, release, upgrade, roll back, or reconcile production
workloads.

## Connect the local target

From an already composed Host directory, start the complete connected local
path:

```sh
cd ./support-desk
lenso dev up --console-root ../lenso-console
```

The command starts the Host, auto-start Provider Services, and Console; creates
loopback-only signed enrollment material; reconciles Module-owned UI artifacts;
and connects the exact topology before reporting the System ready.

For a separately prepared connection bundle, use the same public idempotent
entrypoint:

```sh
LENSO_CONSOLE_TOKEN='<operator-session-token>' \
  lenso console connect \
  --console-url http://127.0.0.1:3030 \
  --bundle .lenso/console-connect.json
```

Use `--token-file` with a private regular file for non-interactive operation.
The bundle binds signed enrollment receipts, an optional exact Console
Composition artifact effect, and the digest-bound System Connection request.

## Underlying enrollment contract

The Support Desk local acceptance submits its signed bilateral exchange to:

```text
POST /api/console/v1/enrollment-receipts
```

The body contains only `{offer, receipt, baseUrl}` and the route requires
`console.system.connect`. Console validates both signatures against its
server-only allowlisted Ed25519 trust configuration before storing the exact
Enrollment Grant and Receipt. In this supported slice, `baseUrl` must be a
loopback target. The CLI-owned `lenso-local-control-adapter` is bound as
`workload-control:<system>` and does not use business enrollment; every other
topology Service requires an active signed enrollment.

This endpoint is not remote or production self-service enrollment. A remote
production target still requires the approved mTLS and certificate-pinning
transport seam.

## Underlying System connection

The public connection boundary is:

```text
POST /api/console/v1/system/connect
```

The authenticated request contains one exact `lenso.system.v2` topology, its
SHA-256 digest, and a Management Binding for the same System. Console validates
that services, modules, workloads, adapters, permissions, and policy all agree
before storing the connection.

Whole-System reads require `console.system.read`; connection requires
`console.system.connect`. Service-scoped grants cannot authorize either route.

An unsigned registry write is never a connection shortcut. Connect validates
the exact active enrollment, Management Binding, and advertised Core contract.

## Read status

```text
GET /api/console/v1/system
```

The response and **Services** page show direct state for each object:

| State | Meaning |
| --- | --- |
| `connected` | The exact contract, digest, binding, and live target agree. |
| `unavailable` | The declared target cannot currently be observed; the reason identifies the failing boundary. |
| `incompatible` | A protocol, schema, artifact, or capability does not match. |
| `unmanaged` | An observed or enrolled object is outside the current topology and Management Binding. |

Console does not synthesize a second app-wide score. A Service can be connected
while one Module or Adapter has its own actionable state.

## Module Surfaces

A Module-owned UI is an immutable `console_ui_esm` artifact in the same Module
Release as its manifest. Console validates the artifact digest, generated
`lenso.console-module.v1` manifest, protocol range, entries, styles, Module
identity, and exact System receipt before loading it in the Shell.

The Surface uses the public `@lenso/console-module-api` and
`@lenso/console-ui` packages with the injected typed Host API. For business
records it calls a generated client through the same-origin Surface Gateway.
The server rechecks the authenticated Console actor, Module identity,
artifact digest, Module Release digest, contract digest, and allowed operation
ID from the Surface Grant on every request.

Service bearer tokens and Adapter credentials stay on the server. Browser code
never receives them and never connects directly to a business Service.

Continue with [Module Console UI](/docs/console-packages) for artifact authoring
or [Business APIs and Console Surfaces](/docs/admin-surfaces) for operation
design.

## Workload Control

Workload routes are same-origin Console Service endpoints below:

```text
/api/console/v1/systems/{systemId}/workloads
```

The connected topology must name stable Workload references and bind a typed
`lenso.workload-control.v1` Adapter. Console derives the actor, sends only the
declared action, persists the asynchronous Operation Record, and polls the
operation identity to a terminal state.

Local Adapters may support Suspend/Resume or Stop/Start. An unreachable Adapter
produces `unknown` observation state with no revision. Mutations fail closed;
they are not queued, rerouted, or guessed from process state. The active
Adapter and Console Workload cannot target themselves through this path.

## Access control

An installed Console Service has no default credentials. Bootstrap its first
password user and audited Operator role from the external installation
authority:

```sh
lenso console operator bootstrap \
  --console-root ../lenso-console \
  --console-url http://127.0.0.1:3030 \
  --identifier admin@example.com
```

Interactive terminals prompt without echoing the password. Automation must use
`--password-stdin` or a private regular file through `--password-file`. Do not
put Service bearer tokens in a browser build.

For authentication capability boundaries, read
[Auth Capabilities](/docs/auth-capabilities).

## Operational boundary

- Console reports connected application state; it does not own application
  composition.
- Business writes go through declared Business APIs and Surface Grants.
- Typed management operations execute in their owning Service or Adapter.
- Production release and deployment remain external to Console.
- Console outage does not stop Autonomous Service business execution.