Installation
Install online
On Ubuntu 22.04 LTS or newer (x86_64), download and run the online installer.
No repository checkout is needed. Run it as the intended service user, not with
sudo bash; it requests sudo only for missing system packages.
The download entry requires Bash, curl or wget, CA certificates and python3
(sudo apt-get install curl ca-certificates python3 if missing).
Set VERSION to main for the development version, or replace it with an actual
release tag such as vX.Y.Z. Only tags containing the online installer are supported.
With curl:
VERSION=main && curl -fsSL "https://raw.githubusercontent.com/llm-d-incubation/llm-d-lens/${VERSION}/scripts/LensInstaller-Ubuntu-x86_64-online.sh" | bash
Or with wget:
VERSION=main && wget -qO- "https://raw.githubusercontent.com/llm-d-incubation/llm-d-lens/${VERSION}/scripts/LensInstaller-Ubuntu-x86_64-online.sh" | bash
The installer reads interactive input from /dev/tty. After validating the source
archive, it saves LensInstaller-Ubuntu-x86_64-online.<unique-id>.sh in the current
directory and prints the path; existing files are not overwritten. Use a writable
working directory. The complete script body must arrive before it can execute.
In automated Bash shells, enable set -o pipefail so downloader failures also
produce a nonzero pipeline status.
Interactive mode asks for the install directory (default $HOME/llm-d-lens) and
ports (app 3000, internal backend 8081); press Enter to accept each default.
The installer downloads a commit-pinned source archive, then provisions Node,
Python 3.11+ and a virtualenv, configures PostgreSQL, builds the app and sets up TLS.
If a compatible Python is missing, it uses pinned uv to install private Python 3.12
under the installation's .tools/; system Python is unchanged.
It accepts only a new or empty install directory, not an existing installation.
Version selection
The script embeds its source version; no version argument is needed or accepted.
main installs the development branch as it exists when the script runs. Release
scripts install their tagged source. Both resolve to a commit SHA before downloading;
the installed .lens-version.json records the version, SHA and installation time.
Source pinning does not lock every transitive npm/Python dependency.
Network and failures
Allow HTTPS access to raw.githubusercontent.com, api.github.com, codeload.github.com,
Node.js and package registries, and Ubuntu package mirrors. Private Python provisioning
also downloads from GitHub release assets. Existing HTTP_PROXY, HTTPS_PROXY and
NO_PROXY settings are inherited; certificate verification remains enabled.
If sudo filters proxy variables, configure apt's proxy separately.
Logs are private files under $LENS_LOG_DIR (default ~/.local/state/lens/logs/).
They can contain installer-generated database credentials; do not publish them.
Temporary downloads use $LENS_SCRATCH_DIR and are removed on exit. Downloads and
archive checks finish before the install directory is changed; later failures may
leave a partial installation, which is retained for diagnosis. There is no automatic
upgrade, rollback or deletion of that directory. GitHub API rate-limit/network failures
are reported without falling back to another version.
For scripted or CI installs without a terminal, replace the final | bash with
| bash -s -- --silent.
Other installer options can follow --silent. A saved script can still be run
directly with bash <saved-script-path> [options].
Common options:
| Option | Purpose |
|---|---|
--install-dir DIR | Install location (default $HOME/llm-d-lens). |
--app-port PORT | Web app/API port (default 3000). |
--backend-port PORT | Internal FastAPI backend port (default 8081). |
--no-https | Serve plain HTTP instead of auto-HTTPS (self-signed cert). |
--no-start | Install without starting services. |
--db-mode embedded|external | Use the built-in database or an external one. |
-h, --help | Show every option. |
Manage the installation
The installer writes lensctl.sh into the install directory:
"$HOME/llm-d-lens/lensctl.sh" start
"$HOME/llm-d-lens/lensctl.sh" status
"$HOME/llm-d-lens/lensctl.sh" stop
To remove an installation, run "$HOME/llm-d-lens/lensctl.sh" uninstall;
data is kept by default. Use --purge to remove data as well, or --keep-data
to skip the data prompt. Embedded database retention is controlled separately by
--keep-db / --purge-db. The online installer itself does not accept uninstall flags.
To upgrade an existing installation instead of a fresh install, see Upgrade.
Install and run from source
From the repository root, use the local source launcher instead of the Ubuntu installer's packaged deployment:
scripts/lens-local.sh start
scripts/lens-local.sh status
The launcher prepares Node.js, npm dependencies and the Python environment,
then runs the source frontend on port 5173, the Node API on 3000, and the
Python backend on 8081. This serves source code through Vite; it does not
replace the production build command below. Use npm run dev:web when managing
the Python backend separately.
scripts/lens-local.sh start and restart regenerate and validate the reuse map before
changing services. Invalid registrations block startup without stopping existing
services; pending user decisions warn without being resolved automatically.
To constrain deployments to a node, pass --target-node NODE and optionally
--kubeconfig FILE, or set TARGET_NODE and KUBECONFIG. No target-specific
configuration file is needed. See the CLI Reference for
preflight requirements and every scripts/lens-local.sh subcommand.
Build and test
npm run build
npm run type-check
make test-js
make test-python
Documentation site
This site is built with Docusaurus. Preview it locally with hot reload:
npm run docs:dev
Validate configuration and page paths:
npm run docs:check
The generated MCP catalog is required for the assistant and Node server. Regenerate it when backend routes change; Docker builds generate it automatically.