The configuration file
quanthea can be set up entirely from a file: the server settings, the users, sign-in, the data sources, the model, retention, queries, charts, the alert settings and plugins. Keep it in Git and an instance can be rebuilt from it. Everything the file leaves out stays editable in the interface.
The file is optional. Without one, an admin sets everything up in the interface.
Where it goes
QUANTHEA_CONFIG names a YAML or JSON file, or a directory whose *.yaml, *.yml and *.json
files are read in name order. In the Docker image it is /etc/quanthea, empty until you mount a
file there:
docker run -d --name quanthea -p 3000:3000 \
-v quanthea-data:/data \
-v quanthea-keys:/keys \
-v ./quanthea.yaml:/etc/quanthea/quanthea.yaml:ro \
--env-file .env \
ghcr.io/jboix/quanthea
Each top-level key is a section. A key is set in one file only, so a directory can split the sections across files.
configuration.schema.json describes every field. Start the file
with this line, and editors that read it complete and check the file as you type:
# yaml-language-server: $schema=https://raw.githubusercontent.com/jboix/quanthea/main/docs/configuration.schema.json
Secrets and variables
A secret is never written in the file. Each password, client secret, API key and connector credential is a whole reference:
"${NAME}": the environment variableNAME. Quote it inside{ }, where YAML would read it otherwise.file:/run/secrets/name: a file, such as a Docker or Kubernetes secret.
Any other text value may use ${NAME} too, such as host: ${DB_HOST}. $${ writes a literal
${. An unset variable stops the server, and no message ever quotes a secret.
When it applies
- quanthea reads the file at startup. Restart it to apply a change, to the file or to a secret it refers to.
- A mistake applies nothing: the server stops and lists every issue.
- What the file declares is read-only in the interface, with a badge naming the file.
- Remove an item from the file and it stays, editable again. With
provisioning.prune: true, quanthea deletes it instead (a user is disabled, a provider removed).
server
The system settings. An environment variable wins over the file, and the file over the default. Settings → Server shows each one and where it comes from.
server:
publicUrl: https://quanthea.example.com
trustedProxyHops: 1
logLevel: info
logFormat: json
| Key | Default | What it sets |
|---|---|---|
publicUrl | none | The address people reach quanthea at. Sign-in providers need it. |
trustedProxyHops | 0 | Reverse proxies in front that add to X-Forwarded-For, up to 5. |
host | every one | The address to listen on, such as 127.0.0.1. |
port | 3000 | The HTTP port. |
dataDir | ./data | The SQLite database. /data in the image. |
keysDir | ./keys | The generated keys. /keys in the image. |
webDir | the built app | The web app the server serves. |
logLevel | info | debug, info, warn or error. |
logFormat | text | text for readable lines, json for one object per line. |
Environment variables lists the variable for each.
users
Users by email, or admin, who signs in as admin with no email.
users:
admin:
password: ${ADMIN_PASSWORD}
ana.keller@example.com:
name: Ana Keller
role: admin
marco.rossi@example.com:
name: Marco Rossi
role: editor
password: file:/run/secrets/marco
tom.weber@example.com:
role: viewer
disabled: true
| Key | Default | What it sets |
|---|---|---|
name | none | The name, set when the user is created. |
role | viewer | viewer, analyst, editor or admin. |
disabled | false | A disabled user signs nothing in. |
password | none | A secret reference. Set only while the user has no password. |
A user without a password signs in through a provider with that verified email. admin needs a
password, and stays an admin. With an admin declared, quanthea creates no admin user of its own.
signIn
Password sign-in and the sign-in providers, by id.
signIn:
passwordSignIn: true
providers:
google:
kind: google
name: Google
join: { mode: domain, values: [example.com] }
clientId: 1234.apps.googleusercontent.com
clientSecret: ${GOOGLE_CLIENT_SECRET}
entra:
kind: entra
name: Microsoft
tenant: example.onmicrosoft.com
clientId: 00000000-0000-0000-0000-000000000000
clientSecret: ${ENTRA_CLIENT_SECRET}
| Key | Default | What it sets |
|---|---|---|
kind | none | github, google, gitlab or entra. |
name | none | The name on the sign-in button. |
baseUrl | null | GitLab only: your own GitLab’s address. null for gitlab.com. |
tenant | null | Entra ID only: the tenant’s id or domain. |
join.mode | invite | Who may join: invite, domain, organisation, group or tenant. |
join.values | [] | The domains, organisations or groups. |
clientId | none | The OAuth client id, in clear. |
clientSecret | none | The OAuth client secret, as a secret reference. |
enabled | true | A provider the file declares needs no test sign-in. |
passwordSignIn: false waits until an enabled admin can sign in through a provider; until then,
each start logs that it is deferred.
connectors
The data sources, by name. config holds the kind’s settings in clear;
secret its credentials, as references.
connectors:
orders:
kind: postgres
config:
host: db.example.com
database: orders
username: quanthea_ro
tls: require
secret:
password: ${ORDERS_DB_PASSWORD}
accessLevel: 3
hiddenFields: [customers.email, customers.phone]
visibility: { mode: except, names: [salaries, audit.*] }
guardrails: { timeoutMs: 15000, maxRows: 100000, maxRangeDays: 180 }
descriptions:
orders: One row per checkout attempt, paid or not.
metrics:
kind: prometheus
config:
url: http://prometheus:9090
logs:
kind: opensearch
config:
url: https://search.example.com:9200
username: quanthea_ro
secret:
password: ${LOGS_PASSWORD}
bucketScripts: true
| Key | Default | What it sets |
|---|---|---|
kind | none | The connector kind, such as postgres, prometheus or a plugin’s. |
config | none | The connection, as the kind’s form has it. |
secret | none | The credentials, each a secret reference. |
accessLevel | 2 | 1 schema only, 2 schema and metadata, 3 aggregates, 4 full access. |
hiddenFields | [] | Fields the model never sees: table.column, a bare column, or a dotted path into a nested field (logs.user.email). Names match in any case, and a hidden object hides every field under it. |
visibility | below | Which tables, indices or collections the connector shows. See what a connector shows. |
bucketScripts | false | On an Elasticsearch or OpenSearch connector, whether a query may hold a script of its own in bucket_script and bucket_selector. See bucket scripts. Another kind refuses true. |
guardrails | below | timeoutMs 10000, maxRows 50000, maxRangeDays 90. |
descriptions | {} | Descriptions of tables and columns, read by the model. |
visibility has three fields. showSystem (false) shows the source’s own objects, such as dot
indices or pg_catalog. names ([]) lists names as the schema has them, or patterns such as
logs-*. mode says how the list reads: except (the default) hides the names, only shows
nothing else. With mode: only and no names, the connector shows nothing. A key other than these
three is refused when the file is read, so a misspelt names does not leave the list empty. How
names match, with or without case, depends on the source: see
what a connector shows.
A connector the file declared before visibility existed hides system objects from the next
start, as the file’s default says. Write showSystem: true when a dashboard, alert or report
reads one (information_schema, pg_catalog, a dot index), and to keep an Elasticsearch or
OpenSearch connector from resolving index names, which its credentials must be allowed to do
once it hides anything.
The connector’s page edits the same three fields, with a checklist of what the schema found. It counts the threads and pinned dashboards that read an object before hiding it. The file does not: a pinned dashboard that reads an object the file hides shows the refusal on its panels. On a connector the file declares, the section is read-only.
config is stored in clear. A URL in it must not hold a username or a password, even from a
variable, and a host field must not hold @: put the username in the kind’s username field and the password in secret.
A connector the file declares that already exists is taken over; its kind never changes. Its
descriptions stay editable in the interface unless the file declares them. The connection form of
each kind lists its config fields; the schema file has them too.
model
The model gateway, managed as a whole.
model:
defaultProviderId: anthropic
providers:
- id: anthropic
name: Anthropic
provider: anthropic
baseUrl: null
models:
plan: claude-haiku-4-5
build: claude-sonnet-5
repair: ''
metadata: claude-haiku-4-5
answer: claude-haiku-4-5
apiKey: ${ANTHROPIC_API_KEY}
- id: local
name: Ollama
provider: openai-compatible
baseUrl: http://ollama:11434/v1
models: { plan: '', build: qwen3-coder, repair: '', metadata: '', answer: '' }
apiKey: ${OLLAMA_API_KEY}
- id: azure
name: Azure OpenAI
provider: openai-compatible
baseUrl: https://contoso-ai.openai.azure.com/openai/v1
models: { plan: '', build: gpt-5, repair: '', metadata: '', answer: '' }
auth:
type: oauth-client-credentials
issuer: https://login.microsoftonline.com/<tenant id>/v2.0
clientId: b2e64a1c-9f3d-4c55-8a0e-2f6f7c1d9e10
scope: https://cognitiveservices.azure.com/.default
clientSecret: ${ENTRA_CLIENT_SECRET}
limits:
toolCallsPerTurn: null
tokensPerTurn: null
repairAttempts: 3
behaviour:
planApproval: true
testRun: true
shortReasoning: true
planQueries: false
providerisanthropic,openai,mistraloropenai-compatible.baseUrlisnullfor a vendor’s own API.authis{ type: api-key }when left out: the provider takesapiKey.- With
auth: { type: oauth-client-credentials }, quanthea asks the identity provider for a short-lived token and sends it to the gateway in place of a key. Giveissuer, ortokenUrlfor an issuer without a discovery document,clientId, and thescopeoraudiencethe gateway expects. The secret goes inclientSecret.baseUrlmust be the gateway: a vendor’s own API takes keys only. - Each job’s model may be empty: it then uses the build model.
limitsandbehaviourtake their defaults when left out.toolCallsPerTurnandtokensPerTurnarenullfor no limit: past one, a turn pauses and asks whether to go on.
retention
retention:
binDays: 30
How many days deleted threads and conversations stay in the bin,
30 by default; null keeps them until someone deletes them, and 0 purges at the next hourly run.
queries and charts
The query builders and saved queries, and the chart recipes switched off.
queries:
disabled: [sql-rows]
saved:
- id: active_customers
name: Active customers
description: Customers with a paid order in the range.
language: sql
query: |
SELECT count(DISTINCT customer_id) AS value
FROM orders
WHERE status = 'paid' AND created_at BETWEEN :__from AND :__to
shape: single
charts:
disabled: [flow.sankey]
A saved query’s params declares its placeholders, at most 10: each a name and a kind
(metric, label, table, column, value or duration), with an optional description.
shape says what it returns: long, wide, single, values, matrix, hierarchical,
graph, geo, ohlc or rows. Settings → Queries and Settings → Charts show the
builder and recipe ids.
definitions
Business terms with one meaning, by id. The agent reads the meaning; a panel built from a definition copies its checked body for that query language. A change in the file adds a version of the definition; panels already built keep the copy they made.
definitions:
error-rate:
name: Error rate
synonyms: [failure rate]
meaning: ERROR events, excluding business errors and blocked media, over START events.
bodies:
- shape: ratio
request:
kind: search-ratio
index: core_events
match:
- { field: event_name, value: ERROR }
- { field: data.business_error, op: '!=', value: 'true' }
of:
- { field: event_name, value: START }
meaningis at most 300 characters. It may not name a field hidden on a connector.- A body’s
shapeismeasure,ratioorsegment, and itsrequestis a query builder’s request without itsconnector. At most one body per query language. connectorson a body limits it to those connectors; without it, it applies to every connector of its language.- Bodies from the file are checked but not test-run at startup, since their sources may not answer yet.
alerts
The alert settings, and the quiet hours of every alert that sets none of its own.
alerts:
maxActivePerConnector: 50
notifyOnError: true
quietHours:
timezone: Europe/Zurich
windows:
- { days: [monday, tuesday, wednesday, thursday, friday], from: "22:00", to: "07:00" }
- { days: [saturday, sunday], from: "00:00", to: "00:00" }
exceptSeverities: [critical]
| Key | Default | What it sets |
|---|---|---|
maxActivePerConnector | 50 | The most alerts active on one connector. |
notifyOnError | true | Tell the channels when an alert cannot be checked. |
quietHours | null | When alerts send nothing. null for never. |
quietHours.timezone | The IANA time zone of the clock, such as Europe/Zurich. | |
quietHours.windows | 1 to 8 windows: days, from and to, as HH:MM. | |
quietHours.exceptSeverities | [critical] | The severities that notify whatever the hour. [] spares none. |
daysname the day a window starts on. A window whosetois at or before itsfromends the next day, so Friday22:00to07:00ends on Saturday morning.fromandtothe same make a whole day:00:00to00:00on Saturday and Sunday is the weekend.- Quote the times: YAML reads an unquoted
22:00as a number.
Quiet hours says what an alert does during them.
plugins
Connector plugins, read at startup.
plugins:
pins:
"quanthea-plugin-sqlite": "sha256:f7eb…"
| Key | Default | What it sets |
|---|---|---|
dir | <data dir>/plugins | Where plugins are installed. /plugins in the image. |
pins | {} | The pin of each plugin, as the install prints it. |
allowUnpinned | false | Load plugins without a pin. |
provisioning
provisioning:
prune: false
With prune: true, what the file no longer declares is deleted instead of released: a connector
is deleted, a user disabled, a provider removed. A settings section keeps its values.
What the file can’t declare
Notification channels, the report settings, dashboards, alerts and reports live in the interface. Their state is in the database, which you back up with the data volume.