Host Quickstart

Create a Launchpad app or scaffold a Lenso host and run it locally.

Use this path when you want a local Lenso app that can load modules, run service processes, and serve the Runtime Console.

You will finish with:

a generated service-ready app or host app
optional capability packs for reusable business slices
local Postgres
API and worker processes
Runtime Console at /console

Prerequisites

Rust and Cargo
Docker for local Postgres
a terminal that can run long-lived local services

Install the CLI

cargo install lenso-cli

You can also install the packaged CLI with npm:

npm install -g @lenso/cli

The current GA CLI line is 0.2.13. Verify the installed binary before using a release or support command:

lenso --version

App Composer is the recommended first path. It creates a support-desk app with a host, TypeScript and Rust services, lenso.system.json, lenso.workspace.json, .lenso/launchpad.json, and an App Change Plan that Runtime Console and agents can read.

lenso app list
lenso app inspect support-desk
lenso app compose ./acme-support \
  --blueprint support-desk \
  --addon support-sla \
  --addon customer-profile \
  --apply
cd acme-support
lenso app next
lenso app explain
lenso dev status
lenso dev doctor --write-state
lenso agent task --from-app-plan "add enterprise SLA escalation"
lenso dev up

lenso dev up starts services from lenso.workspace.json, then starts the host. Open Runtime Console at /console; its first screen is /launchpad and shows the generated services, modules, addons, doctor status, checklist, and next operator command.

To compose a reusable slice that carries seed module and service manifests plus agent handoff context, create a capability pack and pass it to App Composer:

lenso capability init support-sla \
  --dir ./capabilities/support-sla \
  --lang ts \
  --for-blueprint support-desk
lenso capability library add ./capabilities/support-sla
lenso capability fit support-sla --repo-root .
lenso app compose ./acme-support \
  --blueprint support-desk \
  --pack support-sla \
  --apply

Capability packs are local composition metadata. They do not replace lenso module install for module capabilities or lenso service install for out-of-process providers.

Create a blank host

lenso host init my-lenso-app
cd my-lenso-app
cp .env.example .env
lenso serve

lenso serve starts the starter Postgres service, runs migrations, then keeps the API and worker running until Ctrl-C. Published lenso-cli builds also copy the bundled Runtime Console into the host, so the API serves it at /console without requiring Node.js or pnpm in the host application.

Open these URLs after the command prints that the services are ready:

/v1/app/status for host API health
/console for Runtime Console

Manual service loop

If you want to run each process yourself:

docker compose up -d postgres
cargo run --bin migrate
cargo run --bin api

Run the worker in a second shell:

cargo run --bin worker

Service workspace loop

For out-of-process providers, create a service and let the workspace file track it:

lenso service create support-suite-provider --lang ts --output-dir services --port 4110
lenso service workspace list
lenso service dev

lenso service dev starts services from lenso.workspace.json, then installed service processes from .lenso/module-services.json, then the host. Workspace commands also read the older .lenso/services.json path when a host has not yet moved to lenso.workspace.json.

After the services are running, check them from another shell:

lenso service workspace check

Add auth with Redis sessions

Generated hosts do not install auth by default. Add Redis-backed auth session lookup only when the app needs it:

lenso module install auth --profile redis-session-cache

The profile enables the auth dependency’s Redis feature, writes REDIS_URL to .env, and records auth.session_cache=redis in .lenso/runtime-config-defaults.json. Provide Redis separately; the starter Docker Compose file starts Postgres only.

If something is blank

Console is unavailable: run lenso console doctor against its independent installation.
A module is not visible: restart the API and worker after installing it.
A Service is not ready: run lenso service doctor <provider> --json.
Launchpad is empty: run lenso dev status in the generated app root.
Launchpad doctor is empty: run lenso dev doctor --write-state.
App lifecycle is unclear: run lenso app next or lenso app explain.

Next step

After the system is running, use the independently installed Lenso Console to inspect managed Services and runtime evidence. If you need to wire profiles, CORS, telemetry, or Service installation settings, continue with Configuration. To add business capability, continue with Module Authoring.

For command options beyond this happy path, use CLI Reference. If the host starts but a module or Console surface is missing, use Troubleshooting.

For blueprint and addon details, read Product Blueprints.

To add real authentication, continue with Built-in Modules.