Configuration

Configuration

Lens reads its settings from boxlang.json under modules.bxLens.settings. You only set what you want to change. The schema and defaults come from the module's ModuleConfig.bx. Restart the runtime (or reload the module) after a change to boxlang.json. A group of settings can also be changed live from the console, see Live settings.

Lens is off by default. There are two surfaces and you switch them on independently:

• the bar, a strip injected into HTML pages for developers (bar.enabled)
• the console, a standalone page at /~bxlens/index.bxm for one server (console.enabled)

{
	"modules": {
		"bxLens": {
			"settings": {
				"bar": { "enabled": true },
				"thresholds": { "slowQueryMs": 50 }
			}
		}
	}
}

Defaults

{
	"bar": { "enabled": false, "access": "local", "allowAllIPs": false },
	"console": {
		"enabled": false,
		"password": "",
		"viewerPassword": "",
		"requireHttps": false,
		"access": "local",
		"sessionMinutes": 30,
		"maxLoginAttempts": 5,
		"lockoutMinutes": 5,
		"actions": true,
		"readOnly": false,
		"overridesFile": "",
		"runTimeoutSeconds": 60,
		"maxStreams": 10
	},
	"collect": { "level": "light" },
	"tabs": { "hide": [] },
	"store": { "enabled": true, "dir": "", "instanceFolder": "", "retentionDays": 15, "maxMB": 500, "staleAfterHours": 0, "queueSize": 20000, "flushSeconds": 30 },
	"ai": {
		"enabled": false,
		"provider": "ollama",
		"model": "llama3.2",
		"baseUrl": "http://localhost:11434",
		"embeddingModel": "nomic-embed-text",
		"temperature": "0.2",
		"timeoutSeconds": 120,
		"maxToolCalls": 8,
		"memoryMessages": 20,
		"maxConcurrentChats": 3,
		"actions": true,
		"rag": true,
		"apiKey": "",
		"apiKeyEnv": "",
		"links": true
	},
	"server": { "name": "", "address": "", "id": "" },
	"checks": { "securityHeaders": true, "slowSample": true },
	"volumes": { "warnPct": 80, "critPct": 90 },
	"dev": { "reloadAssets": false, "license": "" },
	"access": {
		"allowedHosts": [],
		"requireHeader": "",
		"trustProxyHeader": true,
		"proxyHeader": "X-Forwarded-For",
		"proxyPeers": "private"
	},
	"async": { "enabled": true, "queueSize": 2000 },
	"request": { "maxMinutes": 10 },
	"inject": true,
	"contentTypes": [ "text/html" ],
	"excludePaths": [ "/~bxlens/*", "/favicon.ico" ],
	"history": { "trackNonHtml": "", "header": "X-BxLens-Id", "headerAlways": true, "serverHeader": false, "maxRequests": 50 },
	"ui": {
		"theme": "auto",
		"startOpen": false,
		"autoOpenOnException": true,
		"defaultTab": "timeline",
		"height": 360,
		"allowDetach": true,
		"hotkey": "Ctrl+`"
	},
	"thresholds": { "slowRequestMs": 500, "slowQueryMs": 25, "slowTemplateMs": 100, "nPlusOneMin": 3 },
	"editor": { "linkPattern": "vscode://file/{path}:{line}", "remoteBase": "", "localBase": "" },
	"redact": {
		"keys": [ "password", "pwd", "passwd", "token", "secret", "apikey", "api_key", "authorization", "cookie", "credential" ],
		"mask": "[redacted]"
	},
	"limits": { "maxString": 2000, "maxDepth": 4, "maxItems": 100 },
	"collectors": {
		"templates": { "enabled": true, "max": 300 },
		"functions": { "enabled": false, "max": 1000, "minMs": 0 },
		"queries": { "enabled": true, "max": 200, "includeParams": false, "captureCaller": true },
		"http": { "enabled": true, "max": 100, "slowMs": 2000, "errorPct": 5, "minCalls": 20, "repeat": 20, "largeMB": 5 },
		"mail": { "enabled": false, "capture": "meta", "maxMessages": 200, "failurePct": 5, "minMessages": 10, "spoolMinutes": 10 },
		"aiobs": { "enabled": false, "attach": true, "content": "off", "maxRuns": 500, "failurePct": 5, "minCalls": 20, "rateLimits": 3, "mcpErrors": 4, "slowFactor": 3 },
		"exceptions": { "enabled": true, "max": 50 },
		"messages": { "enabled": true, "max": 200 },
		"timers": { "enabled": true, "max": 200 },
		"transactions": { "enabled": true, "max": 50 },
		"logs": { "enabled": false, "max": 200 },
		"scopes": {
			"enabled": true, "url": true, "form": true, "cookie": false,
			"session": false, "request": false, "application": false, "variables": false
		},
		"jvm": { "enabled": true },
		"cache": { "enabled": true },
		"modules": { "enabled": true },
		"executors": { "enabled": true },
		"tasks": { "enabled": true },
		"datasources": { "enabled": true },
		"caches": { "enabled": true },
		"logfiles": { "enabled": true },
		"environment": { "enabled": true },
		"inflight": { "enabled": true },
		"errors": { "enabled": true },
		"reports": { "enabled": true },
		"ask": { "enabled": true },
		"system": { "enabled": true },
		"threads": { "enabled": true }
	}
}

console.allowHeapDump (default false) is read by the code but is not in the declared schema, so it is not in the block above. It is described under console.

bar

The bar shows only to callers the rule allows. Everyone else is not tracked for the bar. See Security.

console

The console needs enabled: true and a password. See Console.

collect

tabs

access

These extra checks apply to the bar and the console.

See Security.

Core

async

request

history

server

Which machine produced a record. Every tracked request, error group and sample, report, query statistic, in-flight entry, history entry, export, audit line and file of the disk store carries this identity, so the data of many servers can be sent to one place and told apart. See Server identity.

Lens detects the identity once at start and looks again at most every five minutes. It never does a lookup while a request runs. Leave the keys empty to detect. Set them when the machine does not report what you want, for example in a container or behind NAT.

All three are boxlang.json only. The BoxLang runtime instance name is read from the environment variable BOXLANG_INSTANCE_NAME or the system property boxlang.instanceName when one is set.

ui

thresholds

notifications

volumes

checks

store

The disk store keeps errors and reports across restarts. It needs BoxLang+ or a trial. Without one, Errors and Reports stay in memory and store has no effect. See Licensing.

retentionHours is no longer declared. If an older boxlang.json still sets it, it still counts (rounded up to whole days, 30 days at most). maxMB used to limit one file and now limits the whole folder, and its default is 500. Files of the older layout (errors.json and reports.json directly in store.dir) are moved into this server's subfolder at the first start. See The store.

ai

Optional help from a language model: the Lensy, Explain with AI and Ask Lens. Off by default. See Ask Lens and AI help, Set up Ollama and the data flow. Everything but apiKey and links can be changed live from the AI page.

MCP servers

The MCP servers Lensy may ask are not in boxlang.json. The admin keeps them on the AI page, and they are saved with the other console settings in config/bxlens-settings.json (or console.overridesFile) under mcp.servers:

{
  "overrides": { },
  "mcp": {
    "servers": [
      { "id": "boxlang", "builtin": true, "enabled": true, "allowedTools": ["*"] },
      { "id": "acme", "name": "Acme", "url": "https://mcp.example.com/mcp", "builtin": false, "enabled": true, "trusted": false, "allowedTools": ["lookup"] }
    ]
  }
}

The file is checked when it is read, like the console settings: an entry with a bad address, name or id is skipped, listed on the AI page and in the log, and the rest is used. A built-in entry can only change enabled and allowedTools; its address always comes from Lens. See Servers Lensy can ask for the rules.

editor

{
	"editor": { "remoteBase": "/app", "localBase": "/Users/me/projects/shop" }
}

redact

limits

Caps for any value sent to the page.

collectors

Each collector powers one or more panels and has an enabled flag. Most also have a max that caps stored items per request.

The ids logs (the log messages of one request, shown in Messages) and logfiles (the console Logs page) are different collectors. The id queries is shared: collectors.queries.enabled switches the query collector and the console Queries page together.

dev

Live settings

The Settings page of the console can change many settings without a restart. A change applies at once, is saved to config/bxlens-settings.json in the BoxLang home (or the file in console.overridesFile), and is loaded again at the next start. A saved change wins over boxlang.json. The page marks it changed and offers a reset, which removes the override and brings back the value from boxlang.json. See Console settings.

Which settings are live is fixed in the code (SettingsRegistry). Nothing else can be changed from the browser.

The locked settings that the page lists show their value and the label boxlang.json only. A password or API key shows only set or not set. A key that is not on the live list is refused by the server with an error. If console.readOnly is true, or the caller is a viewer, nothing can be changed. A value that is not valid, for example a number out of range, is refused and nothing is saved. An entry that is not valid in the saved file is ignored at the next start and a warning is logged.

Moving from older settings

Earlier builds had one top-level switch and one access rule for the bar. They map like this.

checks.* and dev.* were read with defaults but not declared in the schema. They are declared now, with the same names and defaults, so no change is needed. console.allowHeapDump is the one key that is still read without being declared.

The old default allowed private networks. The new default, "local", is loopback only. To keep the old behavior set "bar": { "enabled": true, "access": [ "local", "private" ] }.

Per request overrides

lensEnable() and lensDisable() switch Lens for one request. The access rules still apply.