Skip to Content
OperatingConfiguration
Operating · Configuration

One file, and refusals instead of defaults.

What you will achieve

Change a saved setting of an installation, then apply it. Know which rules the installer checks, and the fix for each refusal.

What it is for

An installation has one configuration file: .novuslens.env in the installation directory. ./lens setup writes it. Every later command reads it and passes it to Docker ComposeDocker ComposeThe Docker tool that starts and connects the services listed in one configuration file.. Setup settings lists every line in the file, its default and the setup question that writes it.

The installer ignores product settings inherited from your shell. A DATABASE_URL or CONWAY_PROFILE left from development work never reaches the installation. Variables that start with CONWAY_, NOVUSLENS_, MYCELIUM_, COMPOSE_, POSTGRES_ or DATABASE_ come only from the file.

Change a setting

ToRun
Answer the setup questions again and save, without deploying./lens configure, then answer No to reuse the saved configuration
Answer every question again, then deploy./lens setup --interview
Answer every question again, then continue an interrupted deployment./lens resume --interview
Apply a saved change./lens start

Each question offers the saved answer as its default, so press Enter to keep it. The questions never ask for the secrets, the identity salt, the project name or the meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. network prefix again. Setup keeps them.

You can also edit a line in .novuslens.env directly, then run ./lens start. deploy checks the whole file first, and recreates each service whose settings changed.

Logging

Python services and the user interface server read the same log settings. Add CONWAY_LOG_LEVEL or CONWAY_LOG_JSON to .novuslens.env. Put the value in double quotes, such as CONWAY_LOG_LEVEL="DEBUG". Setup keeps both lines when it runs again. Run ./lens start to apply them.

VariableDefaultEffect
CONWAY_LOG_LEVELINFOThe lowest level written: DEBUG, INFO, WARNING, ERROR or CRITICAL, in any case. Other values stop the service and name the setting.
CONWAY_LOG_JSON01 writes one JSONJSONJavaScript Object Notation: a text format for data, using named fields, lists and values. Configuration files and service messages use it. object per log line; 0 writes plain lines. Other values stop the service.
NO_COLORunsetAny value turns off terminal colour. Files and pipes never carry colour.

How it works

Compose reads the file to fill in compose.yml. Each service receives only the settings that compose.yml names for it. Some values are fixed in compose.yml and are not settings:

ValueFixed atWhy
CONWAY_PROFILEcustomerEvery installation runs the customer profileDeployment profileA setting that selects customer or development behaviour. Customer mode refuses development credentials and uses the signed-in session as the identity.. It turns each development convenience into a refusal.
DATABASE_URLThe installation’s own postgres serviceThe database runs inside the installation.
NOVUSLENS_MESH_HTTP_ADDR and NOVUSLENS_MESH_HTTP_BASEmesh-0 and 8400The services reach the mesh on the private network.

The Strategy and sweep models follow CONWAY_COMPASS_MODEL.

Invariants and failure behaviour

The installer checks the whole file before it runs Compose. It refuses at the first problem and names the line.

  • Every required setting must be present, and the file must hold no other line. A network or advanced setting may be left out; it then keeps its default.
  • CONWAY_PROFILE must be customer.
  • Each secret needs at least 24 characters and cannot be a public development value.
  • NOVUSLENS_MESH_NETWORK must be a private IPv4 prefix of three octets, such as 10.239.58.
  • NOVUSLENS_UI_PORT must be a port number. NOVUSLENS_PROJECTION_INTERVAL must be at least 5 seconds.
  • Only one demo can be chosen. The Meridian demo needs a model server.
  • CONWAY_LLM_ENDPOINT must be an HTTPHTTPHypertext Transfer Protocol: the rules a browser or program uses to send a request to a web service and receive its response. or HTTPSHTTPSHTTP carried over an encrypted connection, so the contents are protected while travelling between the caller and the server. address ending in /v1/chat/completions, without credentials, and not a loopbackLoopbackA network address that refers to the same host, such as 127.0.0.1. Other hosts cannot reach a service through that address. address.
  • The OpenRouter endpointEndpointA particular address on a service that accepts a defined kind of request. needs CONWAY_LLM_API_KEY.
  • NOVUSLENS_UI_BIND must be an IPv4 address. Any address other than 127.0.0.1 needs NOVUSLENS_TLS_PROXY=1.
  • NOVUSLENS_TLS_PROXY and NOVUSLENS_MCP_EXPOSE must be 0 or 1. CONWAY_OBSERVATION_TTL_DAYS must be a number above 0.
  • NOVUSLENS_WEBHOOK_ALLOWLIST must be lower-case host names separated by commas, without spaces.

Each service that reads a secret also refuses to start on a missing or development value in the customer profile.

When something goes wrong

  • Full traceback with local variables: …/traceback-….json. A service stopped on an error it did not expect. The file holds every local variable, so it can hold secrets. Only the service’s own user can read it. Read it to diagnose the error, and share it only with someone allowed to see the customer’s secrets. A one-off containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host. deletes the file when it stops: the bootstrap’s status check, the Meridian load and a cli command each run in one. The error printed above that line is still in the output. The bootstrap itself runs in the init container, which stays after it stops: copy its file out with ./lens compose -- cp init:<path> ..

  • Set the missing field: … A line is missing from .novuslens.env. Run ./lens setup --interview to write it again.

  • Remove the unsupported field: … The file holds a line setup does not write. Remove it. A setting not listed in Setup settings has no effect on this installation.

  • … cannot use a public development secret or … needs at least 24 characters. A secret was edited by hand. Restore the line from your protected copy of the file. Do not generate a new identity salt for an installation that holds records.

  • CONWAY_LLM_ENDPOINT cannot use loopback inside Docker. The services run in containers, where localhost is the container itself. For a model server on this host, use http://host.docker.internal:11434/v1/chat/completions.

  • OpenRouter needs CONWAY_LLM_API_KEY. Create a key at openrouter.ai, then run ./lens setup --interview.

  • NOVUSLENS_UI_BIND … would serve sign-in over plain HTTP on the network. A network address is saved without a declared HTTPS proxy. Run ./lens setup --interview and answer proxy. Network access explains the proxy.

Last updated
OverviewStarting, stopping and health