Switches and settings

Every switch, every setting, and where each value comes from.

Switches and flags#

Every on/off or mode choice in one place. Settings marked page are on the Settings page (and can also come from .env); the rest live where the object is.

Switch	Where	Default	Effect
Library on or off (`LIBRARY_ENABLED`)	Settings > Library	on	Off hides the Knowledge menu, the document tools and the API; nothing is deleted.
Documents may be sent to the AI model	Collection settings	on	Off: the collection is stored, split and searchable by words and meaning (local embedding), but no model ever sees it: no source page, no OCR, no topics, no link suggestions, and Alfred cannot read it.
Agents may read this collection	Collection settings	on	Off keeps Alfred and MCP clients away from the collection entirely, whatever the grants.
Usage tag (public or internal)	Collection settings	internal	Guidance returned with every result so agents know whether they may quote the content to customers. Not an access rule.
Collection grants (read, write, manage)	Collection access table	none	The only thing that decides who and what can read, write or manage a collection. Tokens are read only.
Editor role	Users	off	Needed (with a write or manage grant) to ingest, edit and approve documents. Admins always have it.
Entitlements (confidential, personal, restricted, data)	Per user and per token	see Access control	What each credential may see of the model's data. Restricted is never on by default and every grant is logged.
Agents may read rows	Per connector	on	Off: `query_data` refuses, and agents can still plan queries.
Four-eyes rule	Settings > General (page only)	off	Whoever changed a draft cannot publish it.
Settings locked (`SETTINGS_LOCKED`)	`.env`	off	The Settings page becomes read-only; only `.env` counts.
Reasoning (`CHAT_REASONING`)	Settings > AI	off	Let reasoning models think first: better on hard questions, slower and dearer.
Storage driver (`STORAGE_DRIVER`)	Settings > Storage	local	`local` or `s3`. Choose before the first upload.
Render pages with the browser service (`FETCH_RENDER`)	Settings > Web capture	auto	`never`; `auto` (only pages with almost no text without JavaScript); `always`. Needs the browser service address.
Background workers in this process (`LIBRARY_WORKERS`)	Settings > Library	2	`0` when a separate worker container does the work.
Service role (`SERVICE_ROLE`)	`.env`, set by `docker-compose.worker.yml`	all	`all`: web and workers in one process; `api`: web only.
Embedding provider (`EMBEDDING_PROVIDER`)	`.env`	local	`local` runs in the container; a remote model needs `EMBEDDING_MODEL` and `EMBEDDING_DIM`.
Reranker (`RERANK_URL`)	Settings > AI	off	Sharpens Library search when set; if it fails the order simply stays.
Keep tool responses in the log (`ACTIVITY_RESULT_CHARS`)	Settings > General	8000	`0` keeps only the summary.
Realistic values from the AI model	Demo database build	off	One model call per entity proposes fictional values; only names and descriptions are sent.

Settings and configuration reference#

All settings are environment variables, normally in .env. The ones marked ⚙ can also be changed by an admin on the Settings page (Admin → Settings):

The change applies on the next request, with no restart. Rate limits switch over at once; the sign-in duration applies to new sign-ins. Other app processes pick a change up within 5 seconds.
Each value comes from, in order: the page, .env, the built-in default. Each row shows which; Reset removes the page value and shows the .env value it goes back to.
Values are checked (type and range); a bad value is refused with a message.
Every change goes to the audit log with the old and new value.
The OpenRouter key set on the page is stored encrypted and never sent back: the page only says whether one is set.
SETTINGS_LOCKED=true makes the page read-only and ignores values stored there, for teams that keep configuration in files. The four-eyes rule has no variable and stays editable on the page.

Settings the app needs before it can reach its database, the ones that describe the deployment (proxies, ports) and the embedding model (changing it means re-embedding) are environment only.

Setting	Default	Range	Meaning
`DB_PASSWORD`	required		PostgreSQL superuser, used only to create the app's account on first start.
`APP_DB_PASSWORD`	required		The app's own database account (`studio_app`).
`SECRET_KEY`	required		Signs sessions and derives the keys that encrypt connector passwords and the OpenRouter key and salt masked values. Changing it later means re-entering connector passwords and the key.
`INITIAL_ADMIN_USERNAME`, `INITIAL_ADMIN_PASSWORD`	`admin`, required		The first administrator, created on first start.
`HTTP_BIND`, `HTTP_PORT`	`127.0.0.1`, `8080`		Where the app listens (docker-compose).
`CLIENT_IP_HEADER`, `TRUSTED_PROXIES`	`X-Forwarded-For`, private networks		How to find the real client behind a proxy (see Running behind a proxy).
`RATE_PER_S`, `RATE_BURST` ⚙	`20`, `60`	1-1000, 1-10000	API and MCP requests per client address: steady rate and burst.
`LOGIN_PER_MIN` ⚙	`10`	1-100	Sign-in attempts per client address per minute.
`ALFRED_PER_MIN` ⚙	`20`	1-600	Alfred questions per user per minute.
`INGEST_PER_MIN` ⚙	`20`	1-600	Heavy actions one user may start per minute: uploads, web addresses, refreshes, page regeneration and edits, topic revisions, link suggestions, interview drafts, exports.
`SESSION_HOURS` ⚙	`12`	1-720	Browser session lifetime.
`ACTIVITY_DAYS` ⚙	`30`	1-3650	How long the activity log is kept.
`ACTIVITY_RESULT_CHARS` ⚙	`8000`	0-100000	How much of each tool response the activity log keeps (`0`: none, only its size).
`LLM_BASE_URL` ⚙	OpenRouter's address		The AI endpoint: any OpenAI-compatible server. Normally set on the Settings page.
`OPENROUTER_API_KEY` ⚙	empty		Key for the AI endpoint (the name is historical). Alfred, the AI step of the demo database, and remote embeddings. Optional for a server that needs none.
`CHAT_MODEL` ⚙	`openai/gpt-6-luna`		Assistant model: Alfred's, and the default of other AI features (any model with tool calling).
`CHAT_REASONING` ⚙	`false`		Let reasoning models think first (better on hard questions, slower and dearer).
`ALFRED_TEMPERATURE` ⚙	`0.2`	0-1	Alfred's temperature.
`ALFRED_MAX_LOOKUPS` ⚙	`10`	3-20	Tool rounds per question before Alfred answers with what it found.
`ALFRED_TOOL_RESULT_CHARS` ⚙	`16000`	2000-64000	Tool results longer than this are cut before the model reads them.
`AGENT_MAX_ROWS` ⚙	`100`	10-1000	Rows `query_data` returns to Alfred and MCP clients. A longer result gives the total (`total_rows`) and a note suggesting counts, groups or filters; rows are not paged.
`CONSOLE_MAX_ROWS` ⚙	`500`	10-5000	Rows in the SQL console (a connector can set a lower limit).
`LIBRARY_ENABLED` ⚙	`true`		Turns the Library on or off (nothing is deleted).
`LIBRARY_WORKERS` ⚙	`2`	0-8	Documents processed at once by the web process; `0` when a separate worker container does the work.
`LIBRARY_MAX_UPLOAD_MB` ⚙	`100`	1-2000	Largest upload.
`STORAGE_DRIVER` ⚙	`local`	`local`, `s3`	Where original files are kept.
`S3_ENDPOINT`, `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY`, `S3_SECRET_KEY` ⚙, `S3_PATH_STYLE`, `S3_PREFIX`	empty		Any S3-compatible bucket; the secret key is stored encrypted.
`MODEL_WRITER`, `MODEL_VERIFIER`, `MODEL_ANALYZER`, `MODEL_TOPIC_WRITER`, `MODEL_INTERVIEW`, `MODEL_OCR` ⚙	empty		A model per Library role; empty uses the assistant model.
`MAX_AMENDMENT_ROUNDS` ⚙	`3`	0-8	Correction rounds for a source page before it goes to a person.
`WRITER_SECTION_TOKENS` ⚙	`8000`	1000-100000	Longest text written in one go; longer documents are written in sections.
`OCR_MAX_PAGES` ⚙	`100`	1-1000	Most scanned pages read per document.
`DUPLICATE_SIMILARITY` ⚙	`0.92`	0.5-1	Similarity at which a new topic is held as a probable duplicate.
`LIBRARY_MIN_SIMILARITY` ⚙	`0`	0-1	Smallest similarity for a passage to count as a match.
`RERANK_URL`, `RERANK_MODEL`, `RERANK_API_KEY` ⚙	empty		Optional Cohere-style reranker for Library search.
`FETCH_ALLOWED_HOSTS` ⚙	empty		Internal hosts or networks web capture may reach anyway.
`FETCH_MAX_MB` ⚙	`25`	1-200	Largest web page or file captured.
`FETCH_RENDER` ⚙	`auto`	`never`, `auto`, `always`	Use the browser service for pages built by JavaScript.
`FETCHER_URL`, `FETCHER_TOKEN` ⚙	empty		Address and shared secret of the optional browser container.
Four-eyes rule ⚙	off		Page only: whoever changed a draft cannot publish it.
`SETTINGS_LOCKED`	`false`		`true`: the Settings page is read-only and only `.env` counts.
`EMBEDDING_MAX_TOKENS`	`512`		How much of a passage the embedding model reads. The Library cuts documents to about 75% of it.
`EMBEDDING_PROVIDER`	`local`		`local` runs the model in the container (about 30 ms per query, no key). `openrouter` uses a remote model through OpenRouter.
`EMBEDDING_MODEL`, `EMBEDDING_DIM`	`BAAI/bge-base-en-v1.5`, `768`		The embedding model and its vector size, any size pgvector stores (1 to 16000). The database tables are created for that size. Starting with a different size converts them, empties the vectors and recomputes them in the background.
`CONNECTOR_FILES_DIR`	`/app/data`		Where SQLite and DuckDB files may live.
`SAMPLEDB_PASSWORD`, `SAMPLE_MARIA_PASSWORD`, `SAMPLE_CH_PASSWORD`	empty		Only for the demo databases of `docker-compose.demo.yml`.

Advanced (rarely changed; not in .env.example):

Setting	Default	Meaning
`DATABASE_URL`	set by docker-compose	The app's connection to its PostgreSQL, as the least-privileged `studio_app` account.
`DATA_DB_NAME`	`semantic_data`	Name of the demo database inside the app's PostgreSQL.
`DATA_DIR`	`/app/data`	The mounted data folder. The Library keeps its files in `library` below it.
`SERVICE_ROLE`	`all`	`all`: web and job workers in one process; `api`: web only; the worker container runs `python -m studio.worker`.
`OPENROUTER_BASE`	`https://openrouter.ai/api/v1`	Default of `LLM_BASE_URL`.
`EMBEDDING_QUERY_PREFIX`	the prefix `bge` models expect	Text put before a search query when embedding it; set it for a model that expects another.
`MODEL_CACHE`	`/app/models`	Where the local embedding model is kept.
`FRONTEND_DIR`	the built UI in the image	Where the UI files are served from.

This documentation covers version 0.2.0. Something missing or wrong? Open an issue.