Install a demonstration, then follow its evidence.

Before you start

Check the prerequisites: Python 3.9 or newer, Docker with its Compose plugin and a running engine, and internet access. Get the lens file from your demo provider, with a GitHub login and a personal access token that can read the NovusLens packages.

1. Get the application

Copy lens into a new, empty installation directory. Open a terminal there and make it executable:

chmod +x lens
./lens version

Keep the printed build ID with your demo notes. Run every command on this page from this directory. lens is the only file you need. Setup writes its Compose files and downloads the images.

2. Run setup

./lens setup

Setup pulls the published release this lens file was built for, and prints that choice. It checks Docker and Compose, then asks for your GitHub login and personal access token for GitHub Container RegistryGitHub Container RegistryGitHub’s service for storing and downloading packaged applications used by Docker. (GHCR). The token needs read:packages permission and access to the NovusLens packages. Token entry is hidden. If GHCR_TOKEN is already set, setup uses it without asking.

If setup reports a host problem, run ./lens doctor and follow the fix it names.

3. Answer the setup questions

Use these answers for a first demonstration:

Save the login name and passphrase in your password manager. The operator can administer every organisation in this installation. Setup settings explains every question and the other answers.

Setup saves the answers in .novuslens.env. Keep this file with the installation. It holds credentials, so keep it private.

4. Deploy and sign in

Accept the deployment prompt. Wait for the installer to print the sign-in address. The installer then opens its monitor in the same terminal. Step 5 describes it.

1. Open the printed address in a browser on this host. The default is http://localhost:3111/login.
2. Enter the operator login and passphrase from step 3.
3. Select Sign in.
4. Open Retail Lending.
5. Select Docs. On a phone, select Account menu, then Documentation. Open Product GuideGuideThe help pages inside NovusLens. They explain the pages, input formats and tasks in the version you use. They are product instructions, not evidence about the organisation. to check the help pages.

The web port listens on 127.0.0.1 only, so use a browser on the Docker host. To let people on your network sign in, see Network access.

The example data describes an invented organisation with six organisational units and seven declared dependencies. Its records are labelled told or shown. Read the map and its sources before presenting a findingFindingA difference in the records that needs a decision. It includes its sources and can describe a slow handoff, disputed fact or missing owner..

When sign-in succeeds, open the User Tutorial to follow one issue and inspect its evidence.

Optional: give a colleague a login

This step is optional. Setup created one account: the operator login and passphrase you entered in step 3. That account is an operator for every organisation in this installation. To give a colleague their own login, create an account for them. This example creates a read-only board account for the Retail Lending demonstration:

./lens graph create-viewer --viewer board-reader --role board --org retail-lending --passphrase '<their passphrase>'

The role decides what the account sees. A board account reads the organisation and cannot change its records. The passphrase is on the command line, so your shell history and the process list can record it. Set a temporary passphrase, hand it over privately, and set the one they choose with ./lens graph update-viewer. The command runs inside the installation’s reasoning service, so the installation must be running. ./lens graph create-viewer --help lists the flags. Accounts and stewardship explains the roles, and Run operator commands covers the other administration commands.

5. Watch, check, stop and restart

The monitor shows this installation’s live state. It opens after a successful deployment. To open it later:

./lens monitor

Below its title, the monitor lists each fault it can see, worst first. The services badge reads HEALTHY, ATTENTION, or DOWN when a required containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host. is stopped. It then shows four things:

• Services: each container’s state, health check, restart count, CPU and memory. The init row shows whether initialisation is running or complete.
• Read modelRead modelThe database tables used by the map, Ask and Find. NovusLens rebuilds these tables from its history of recorded changes.: the age of the latest analysis pass for each organisation. A healthy web service does not mean the analysis is current.
• Model server: disabled when you chose no model server, unavailable when a configured server does not answer, and missing when a configured model is not loaded.
• Setup journalInstallation journalA saved record of setup steps, their attempts and whether they started, completed or failed. It records progress, not a backup of application data.: the recorded setup steps and attempts. The journal records the past; the service table shows the present.

Use the arrow keys to select a service. Its last health-check error appears below the table. Press l for its recent logs, r to read again now and q to leave. The logs hide routine lines, such as health checks. Press n to show them. Press v to raise the lowest level shown: information, then warnings, then errors only, then every line again. Press m for the mesh: each node’s address, peers, stored entries, tasks, gossipGossipA way for connected services to pass updates to one another until the updates spread through the group. rate and alarm counters. Press d for the read model’s own records: analysis passes in the last hour, the twinTwinNovusLens’s model of one organisation, built from records about its teams, services and how they rely on one another. It is only as current as those records. of each organisation, the quarantineQuarantineA holding area for a log entry that could not be applied. The entry keeps its error and waits for a retry or an operator., the queues and the database. Press the same key again to return to the setup journal. The fault list also names a mesh node that misses a peer, and an alarm count that rises while you watch. It names a failed analysis pass and a quarantined record too. Credentials show as [secret] in every view.

The monitor only observes. Leaving it, or pressing Ctrl+C, keeps the services running. If Docker stops, the monitor shows the last reading and reconnects when Docker returns. To finish a deployment without the monitor, add --no-monitor to deploy or resume.

Run ./lens status for setup progress and the container list, and ./lens logs for recent service output.

To stop and restart the installation:

./lens stop
./lens start

A stop keeps the database and mesh records in Docker volumes. A volume is Docker-managed storage that survives container removal.

Before presenting findings, check the map’s freshness strip. Status and states explains its messages. For a failed analysis stage, use installation diagnostics.

6. Continue an interrupted setup

Return to the same installation directory. Check the saved progress, then resume:

./lens status
./lens resume

The installer records each started, completed or failed step in a private journal. It checks completed outputs before reusing them. Resume repeats missing or stale work and keeps the credentials, records and mesh addresses.

If a download failed, restore network access before resuming. For a model that needs a newer Ollama, follow the model-server recovery steps.

If a port is taken, change only that setting:

1. Run ./lens resume --interview.
2. Enter an unused web port.
3. Accept the saved demo, operator login and model server.
4. If models are configured, accept their saved endpointEndpointA particular address on a service that accepts a defined kind of request. and model names.

--interview asks every setup question again, with the saved answers as defaults, then resumes. To answer the questions again and then run a full deployment, use ./lens setup --interview. Setup keeps the operator passphrase, application secrets, identity saltIdentity saltA secret value added before employee identifiers are turned into fingerprints. Keep the same value so later imports can still match existing people., project name and mesh prefix. You do not enter secrets again.

The installer keeps the GHCR login in the private file .novuslens-registry.json in the installation directory. Later deployments reuse it. To sign in again, delete that file.

If a journal is damaged or missing

If the installer reports damaged state, stop retrying. Keep the journals, .novuslens.env and the Docker volumes as they are. Collect the diagnostic packet and send the redacted packet to your demo provider.

There is no automatic journal repair. With a verified backup, the installation operator restores it with ./lens restore, which needs the original .novuslens.env.

If the initialisation journal is missing while records remain, the installer refuses to load the demo again. Keep the surviving records, and ask your installation operator or demo provider for an assessed recovery procedure.

Watch the setup questions

Follow the setup questions and see the values entered at each step.

Read the transcript or download the recording.

The recording declines deployment after saving the configuration. To start a saved installation, run ./lens start.

Other demonstrations

• An empty installation: choose none as the demo to load, then import an org chart after signing in.
• The Meridian reference demo: choose a model server first, then meridian. After the application starts, the installer loads Meridian in a one-off container. Its build agent interviews through your model server, so the load can take a while. If it fails, the installer names the failed step; fix the cause, then resume.

Next steps

• Add accounts with Accounts and stewardship.
• Import your own organisation with the org chart import.
• Follow the Operations Tutorial for accounts, imports and later operator tasks.