Setup settings
./lens setup asks the questions below, in this order. It saves each answer as one line in .novuslens.env, in the installation directory.
Keep that file private. It holds the operator passphrase, the application secrets and any model server key.
Change a setting
| To | Run |
|---|---|
| Answer every question again, then deploy | ./lens setup --interview |
| Answer every question again, then continue an interrupted deployment | ./lens resume --interview |
| Accept every default and deploy without questions | ./lens setup --defaults |
--interview offers the saved answers as defaults, so press Enter to keep one.
When .novuslens.env already exists and no model options are supplied, setup first asks whether to reuse it. The default is yes.
--defaults needs NOVUSLENS_ADMIN_PASSPHRASE in the environment. With the default model server, it also needs OPENROUTER_API_KEY.
For published images, it also needs GHCR_TOKEN and GITHUB_ACTOR, unless a saved registry login exists.
Use --llm-source openrouter|none|external|local, --build-model MODEL or --compass-model MODEL to supply non-secret answers.
These options work with setup, configure and resume --interview. Explicit values replace saved answers without asking those questions.
A model ID containing / selects OpenRouter unless --llm-source is explicit. The shortcut free becomes openrouter/free.
Model IDs such as ~deepseek/deepseek-v4-flash-latest keep their leading ~.
Saved models remain unchanged when their model server stays the same, except for fields you explicitly override.
./lens setup --compass-model openai/gpt-6-luna
./lens configure --defaults --build-model free --compass-model freeThe questions
| Question | Default | Writes | Notes |
|---|---|---|---|
| Image version | The release lens passes | NOVUSLENS_IMAGE_TAG | Asked only when no release was given. ./lens setup normally gives one. |
| Web port on this host | 3111 | NOVUSLENS_UI_PORT | The port of the web application. |
| Who opens the web interface | this-host | NOVUSLENS_TLS_PROXY | this-host or proxy. See Network access. |
| Address the web port listens on | 127.0.0.1 | NOVUSLENS_UI_BIND | Asked only for proxy. An IPv4 address. |
| Private meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. network prefix | 10.239.58 | NOVUSLENS_MESH_NETWORK | Asked on the first setup only, then kept. Choose a range that does not overlap your Docker, host or VPN networks. |
| Initial operator login | demo-owner | NOVUSLENS_ADMIN_VIEWER | The first account. It can administer every organisation in this installation. |
| Initial operator passphrase | None | NOVUSLENS_ADMIN_PASSPHRASE | At least 12 characters, entered twice. Kept on a later setup. |
| Model server | openrouter | CONWAY_LLM_ENDPOINT, CONWAY_LLM_API_KEY | One of openrouter, none, external or local. See Model server. |
| Demo to load | retail-lending | NOVUSLENS_DEMO, NOVUSLENS_MERIDIAN_DEMO | One of none, retail-lending or meridian. See Demo to load. |
| Build model | See Models | CONWAY_BUILD_MODEL | Asked only when there is a model server. |
| Compass model | See Models | CONWAY_COMPASS_MODEL | Asked only when there is a model server. |
| Review advanced settings | no | Nothing | yes asks the advanced settings. no keeps each saved or default value. |
Setup then prints a summary of the main settings and asks whether to deploy now.
Setup writes a network or advanced setting to .novuslens.env only when it differs from its default. The projectionProjectionThe regular pass that brings the read model up to date with the canonical log. It runs every 30 seconds by default. interval is the exception: setup always writes it.
Model server
The model server answers the interview and Compass questions. NovusLens maps and records without one.
| Answer | What it does |
|---|---|
openrouter | Sends model requests to https://openrouter.ai/api/v1/chat/completions. Setup takes the key from OPENROUTER_API_KEY, or asks for it. Interview text leaves this host and goes to openrouter.ai. |
none | Uses no model server. The Meridian demo is not offered. |
external | Sends model requests to a server you run. The default endpointEndpointA particular address on a service that accepts a defined kind of request. is http://host.docker.internal:11434/v1/chat/completions, an Ollama server on this host. |
local | Starts an Ollama containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host. inside the installation, at http://ollama:11434/v1/chat/completions. It writes COMPOSE_PROFILES=ollama. |
Demo to load
| Answer | What it loads |
|---|---|
none | Nothing. Import an org chart after signing in. |
retail-lending | Fictional Retail Lending records. Writes NOVUSLENS_DEMO=1. |
meridian | The Meridian reference demo, built through your model server. Writes NOVUSLENS_MERIDIAN_DEMO=1. Offered only when there is a model server. |
Models
| Model server | Build model | Compass model |
|---|---|---|
openrouter | openai/gpt-6-luna | openai/gpt-6-luna |
external or local | gpt-oss:20b | qwen3:30b |
A local server downloads both models. Check that the host has the memory and disk for them.
Advanced settings
| Question | Default | Writes | Notes |
|---|---|---|---|
| Days a measured observation counts as current | 30 | CONWAY_OBSERVATION_TTL_DAYS | A number above 0. An older measurement stays in the record as historical and leaves the current view. It is not erased. |
| WebhookWebhookA web address that receives a message automatically when an event occurs. NovusLens notifications send record identifiers there. hosts that may receive notices | Empty | NOVUSLENS_WEBHOOK_ALLOWLIST | Comma-separated host names, such as hooks.example.com. A webhook host must equal one of them or end with one. Empty allows any host the built-in checks allow. |
| Register the NovusLens tools on the internal mesh gatewayGatewayA service that accepts requests and passes them into another system. The Mycelium gateway gives NovusLens access to the mesh. | 0 | NOVUSLENS_MCP_EXPOSE | 1 lets MCPMCPModel Context Protocol: a standard way for an AI application to discover and call named tools supplied by another program. clients on the installation’s Docker network call the analysis tools. It publishes no port on this host. |
| Seconds between projection passes | 30 | NOVUSLENS_PROJECTION_INTERVAL | Seconds between background analysis passes. At least 5. |
Settings setup writes without asking
Setup also writes these lines. A later setup keeps their values, except the installation directory, which it records again.
| Line | Value |
|---|---|
COMPOSE_PROJECT_NAME | novuslens-demo by default. Docker ComposeDocker ComposeThe Docker tool that starts and connects the services listed in one configuration file. uses it to name the installation’s containers and volumes. Give each installation on one host its own name: deployment, backup and restore refuse volumes that another installation created. |
CONWAY_PROFILE | Always customer. It turns off every development convenience. |
NOVUSLENS_INSTALL_DIR | The installation directory. |
NOVUSLENS_IMAGE_PREFIX | ghcr.io/novus-i2 by default. Where the images come from. |
NOVUSLENS_IMAGE_SOURCE | registry for published images, or build for images built from source. |
POSTGRES_PASSWORD, CONWAY_SESSION_SECRET, CONWAY_SERVICE_TOKEN, MYCELIUM_GATEWAY_TOKEN | Random secrets for the database, sign-in sessions and the internal services. |
CONWAY_IDENTITY_SALT | A random saltSaltExtra data mixed into a value before its fingerprint is calculated. It makes matching or guessing the original value harder. for hashing people’s identities. Changing it breaks the link to records already imported. |
NOVUSLENS_PROJECTION_INTERVAL | 30 unless you change it under Advanced settings. Setup writes it even when you skip them. |
Never change the database password or the 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.. Change another secret only as Secrets describes. A backup holds .novuslens.env, so keep each archive private. Also keep a protected copy of the file. Preserve the installation explains why.
Next steps
- Install a demonstration with the Quick start.
- Let people on your network sign in with Network access.
- Change secrets safely with Secrets.
- Read every environment variableEnvironment variableA named setting made available to a running program. The customer launcher reads these settings from the installation environment file. in the environment variable reference.