Host Quickstart

Compose a Support Desk app, start its connected local environment, and inspect exact status.

This quickstart follows the public Lenso lifecycle end to end. You will create one exact app composition, start its Host and Provider workloads with an independent Console Service, connect the exact topology, and inspect direct object status.

Prerequisites

Rust and Cargo
Node.js and pnpm for the Support Desk Provider
Docker for local Postgres
a checkout of LioRael/lenso-console
a terminal that can keep local processes running

Install the CLI

Install either package that exposes the lenso command:

cargo install lenso-cli
# or
npm install -g @lenso/cli

Confirm the installed version before continuing:

lenso --version

1. Compose

lenso app compose ./support-desk --blueprint support-desk --apply
cd support-desk

The bare blueprint selects auth, notification-worker, and support-api. The pack-backed Support Ticket and Story composition is exercised separately by the product acceptance, which also registers its service-backed Provider before local startup.

Inspect lenso.app.json. It is the exact application composition and lock: app revision and content digest, immutable Module Release selections, resolved dependencies, implementation bindings, and provenance must agree before the System starts.

2. Run locally

lenso dev up --console-root ../lenso-console

The first run securely prompts for the local Console Operator password. For automation, pass --operator-password-file with a private regular file.

This shipped command starts the generated Host and each auto-start entry in lenso.workspace.json, provisions and migrates the local Host and Console Stores, builds Console, configures or reuses the durable Operator, reconciles Module-owned UI artifacts, and connects the exact topology. It writes local connection material under .lenso/; credentials and signing material are not printed.

Keep the command running. Press Ctrl-C to stop the Host, Console, and only the Services started by that invocation.

lenso system dev remains the lower-level System Sandbox command:

lenso system dev --system-file lenso.app.json --dry-run --json
lenso system dev --system-file lenso.app.json
lenso system dev --system-file lenso.app.json --cleanup

The sandbox validates and runs its declared sandbox Workloads and Local Control Adapter. It does not replace the connected Host, Provider, and Console path above.

The connected command is shipped for an already composed Host and an existing Console checkout. It does not by itself claim the broader from-empty-directory browser acceptance tracked by Lenso issue #540.

3. Connect

With --console-root, lenso dev up creates loopback-only signed enrollment receipts, assembles .lenso/console-connect.json, and applies that exact bundle through the public connection entrypoint before reporting the System ready.

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

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 local enrollment path accepts loopback targets only; it is not a remote production self-service path. 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. The bundle binds those receipts, optional Console Composition effects, the exact lenso.system.v2 topology, its content digest, and its Management Binding. Browser code never receives Service or Adapter credentials. Console stores the connection; it does not start, deploy, adopt, or repair the app.

4. Status

Open Console and select Services, or call:

GET /api/console/v1/system

System, Service, Module, Surface, and Adapter projections each report their own connection state and reason: connected, unavailable, incompatible, or unmanaged. Workload operational state is a separate dimension.

For a locally controlled Workload, use the supported Suspend/Resume or Stop/Start action. Console returns an asynchronous Operation Record and polls the Adapter until it reaches a terminal state. If the Adapter cannot be reached, Workload observation becomes unknown and mutation is rejected immediately.

Add a business capability

Modules own business identity whether linked into the Host or provided by a Service. Start with Module Authoring, then expose a typed Business API and a receipt-bound Console Surface when the workflow needs operator UI.

TypeScript @lenso/service-kit supports the Provider tier. Its lenso.service.v1 manifest carries compatibility and local-process metadata; the exact Module Release is installed and invoked through the locked lenso.provider.v1 runtime at /lenso/provider/v1. Use Rust for the Autonomous Service tier. The exact distinction is documented in Service Capability Tiers.

Product Blueprints explains the composition lock.
Lenso Console explains connection, status, Surfaces, and Workload Control.
Examples describes the Support Desk black-box acceptance.
CLI Reference lists the current public entrypoints.