Configuration reference

This page lists every configuration key of the Foundation4 API server and worker processes, with type, default and effect, and describes the order in which the processes read configuration files and environment variables. The page also describes how the Helm charts supply each key, the OpenTelemetry variables and the branding.name key. Operators who change the behavior of a deployment beyond the Helm values need this page. Values reference lists the Helm values that produce this configuration.

Load order

The API server, the workers and the command-line interface (CLI) read the configuration once, at process start, from the working directory /app. Each source overrides the keys that the previous sources set, and sections merge key by key:

1. defaults.yaml. A file in the working directory. The images contain no such file.
2. config/settings.yaml. The charts mount no such file.
3. config/f4ai-*.yaml. Every file whose name starts with f4ai- and ends with .yaml, in byte order of the file name. Files ending in .yml are ignored.
4. Environment variables. Every variable named FOUNDATION4AI__<SECTION>__<KEY>.

In a Helm deployment, /app/config holds the following files, read in this order:

File	Source	Content
f4ai-00-defaults.yaml	Chart ConfigMap	The chart defaults listed in Keys
The configs entries	Values api-server.configs	Operator settings, when the entry name matches f4ai-*.yaml
The secrets entries	Values api-server.secrets	Operator settings that contain secrets, when the entry name matches f4ai-*.yaml
f4ai-zz-*-credentials.yaml	Chart Secret	Database, NATS JetStream and cache addresses, license, application secret and master key

Digits sort before letters, so an operator file named f4ai-10-<topic>.yaml is read after the chart defaults and before the credential files. Environment variables override every file.

The configuration takes effect only when a process starts. A changed value reaches running pods after kubectl rollout restart, as described in Configuration change.

The processes ignore unknown keys, so a misspelled key has no effect and produces no error. A missing required key stops the process at startup with a message that starts with Failed to parse config:.

Chart delivery

The application release creates the ConfigMap foundation4ai-api-server and the Secret foundation4ai-api-server as Helm hooks on every install and upgrade:

• ConfigMap. Holds f4ai-00-defaults.yaml and every configs entry. The value of each entry is a string, usually a YAML block.
• Secret. Holds every secrets entry and the five f4ai-zz-*-credentials.yaml files. The chart builds the credential files from the Secret foundation4ai-core of the core release, which Helm reads from the cluster at render time. helm template and GitOps tools that render offline receive no Secret, so the render fails or the credential files are empty.

The chart mounts both objects at /app/config in the server and worker containers and in the hook Jobs. Every key of the ConfigMap, of the Secret foundation4ai-api-server and of the Secret foundation4ai-core also becomes an environment variable in the server and worker containers. The hook Jobs receive only the variables of foundation4ai-core.

A value in foundation4ai-secrets reaches the processes after an upgrade of the core release, which copies the value into foundation4ai-core, an upgrade of the application release, which rebuilds the credential files, and a restart of the pods. Secrets and keys describes the Secret keys.

The Secret keys and the configuration keys follow two naming schemes. The processes never read the single-underscore names:

Key in foundation4ai-secrets	Configuration key
POSTGRES_URL, or POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DATABASE with the bundled PostgreSQL	database.url
REDIS_URL, or REDIS_PASSWORD with the bundled cache	redis.url
NATS_URL, only when the bundled NATS JetStream is disabled	nats.url
FOUNDATION4AI_APP_LICENSE	app.license
FOUNDATION4AI_APP_SECRET	app.secret
FOUNDATION4AI_APP_MASTER_KEY	app.master.key
FOUNDATION4AI_APP_MASTER_SECRET	app.master.secret

Keys

The "Chart" column shows the value in f4ai-00-defaults.yaml or in the credential files. "Required" means that the process does not start without the key.

Application

Key	Type	Default	Chart	Effect
app.host	String	localhost	0.0.0.0	Address on which the API server listens. The chart value accepts traffic from the Service.
app.port	Integer	8000	8000	Port of the API server. The container port, the probes and the Prometheus annotation are fixed at 8000, so a deployment keeps the default.
app.log_level	String or integer	warn	warn	Log level of the API server and worker processes: off, error, warn, info, debug or trace, or 0 to 5 in the same order. Any other value stops the process at startup.
app.license	String	Required	Credential file	The license, as described in Licensing
app.secret	String	Required	Credential file	The application secret: a 32-byte key in URL-safe Base64. An invalid value stops the process with a message that contains Error decoding secret key.
app.master.key	UUID	Required	Credential file	Identifier of the master key
app.master.secret	String	Required	Credential file	Secret of the master key

Database

Key	Type	Default	Chart	Effect
database.url	String	Required	Credential file	PostgreSQL connection URL, such as postgres://<user>:<password>@<host>:5432/<database>?sslmode=verify-full
database.pool_size	Integer	5	3	Maximum connections of each API server process. Workers always use 1 connection. Database describes the connection budget.
database.schema	String	public	Not set	Schema of the main tables, created at startup when missing. The license check computes the system ID from public, so a deployment keeps the default.
database.embeddings_schema	String	embeddings	Not set	Schema of the pipeline tables, created at startup when missing
database.ca_cert	String	None	Not set	Certificate authority for TLS connections to PostgreSQL, as PEM text. With sslmode=verify-ca or verify-full, the processes and the CLI verify the server certificate against this certificate; prefer and require check no certificate.
database.debug	Boolean	false	Not set	Not read

Cache, queue and gRPC service

Key	Type	Default	Chart	Effect
redis.url	String	Required	Credential file	Redis-compatible cache URL, such as redis://default:<password>@<host>:6379
nats.url	String	Required	Credential file	NATS JetStream URL, such as nats://<host>:4222
nats.bucket	String	Required	documents	Object store that holds submitted document text for 24 hours
nats.stream	String	Required	DOCUMENTS	Stream that holds the processing jobs for 24 hours
nats.documents_prefix	String	document	Not set	Subject prefix of the jobs. The workers consume through the consumer <prefix>-processor. Deployments leave the key unset.
grpc.url	String	Required	http://localhost:50051	Address of the gRPC service. The chart value reaches the sidecar container in the same pod.

The API server and the workers create the stream and the object store at startup when the stream and the object store do not exist, and the workers create the consumer. Scaling and performance describes the queue retention.

Model paths and branding

Key	Type	Default	Chart	Effect
paths.fastembed	String	Required	/data/fastembed	FastEmbed model directory
paths.gpt4all	String	Required	/data/gpt4all	GPT4All model directory
paths.huggingface	String	Required	/data/huggingface	Hugging Face model directory
paths.nltk	String	Required	/data/nltk	NLTK data directory
branding.name	String	Foundation4.ai	Not set	Product name in the API documentation, as described in Branding

Models, packages and air-gapped installs describes the model directories.

Keys without effect

The processes ignore the following keys, which the chart writes:

• database.log_level. Database library logging follows app.log_level, as described in Logging.
• prometheus.url. Set in f4ai-zz-prometheus-credentials.yaml. No process reads the value, and the address that the core chart builds names no existing service.
• routes.openai. The OpenAI-compatible endpoint is fixed at /openai/v1.

Environment variables

An environment variable overrides one key. The name is FOUNDATION4AI__, followed by the key path in upper case with each . replaced by __:

Variable	Key
FOUNDATION4AI__APP__LOG_LEVEL	app.log_level
FOUNDATION4AI__DATABASE__POOL_SIZE	database.pool_size
FOUNDATION4AI__APP__MASTER__KEY	app.master.key

The processes parse numeric values as numbers and true or false as booleans.

The charts set no FOUNDATION4AI__ variables. A configs or secrets entry whose name is a valid variable name becomes an environment variable of the server and worker containers, because the chart loads both objects with envFrom. The same entry also appears as a file in /app/config, which the processes ignore because the name does not match f4ai-*.yaml. Secrets belong in secrets, which the chart stores in a Kubernetes Secret.

api-server:
  configs:
    FOUNDATION4AI__DATABASE__POOL_SIZE: "5"

Configuration change

The following procedure adds an operator configuration file. The example raises the log level for a diagnosis:

1. Add the file to the values file of the application release:

   api-server:
     configs:
       f4ai-10-logging.yaml: |
         app:
           log_level: info

   Expected result: configs holds f4ai-10-logging.yaml.

2. Upgrade the application release:

   helm upgrade --install foundation4ai ./charts/foundation4ai \
     -n foundation4ai -f foundation4ai.values.yaml --wait --timeout 10m

   Expected result: Helm reports STATUS: deployed.

3. Confirm that the file is mounted:

   kubectl -n foundation4ai exec deploy/foundation4ai-api-server -c server -- cat /app/config/f4ai-10-logging.yaml

   Expected result: the content of the file. The credential files in the same directory contain secrets and are not printed.

4. Restart the API server and the workers, which read the configuration only at startup:

   kubectl -n foundation4ai rollout restart deploy/foundation4ai-api-server deploy/foundation4ai-api-server-worker
   kubectl -n foundation4ai rollout status deploy/foundation4ai-api-server
   kubectl -n foundation4ai rollout status deploy/foundation4ai-api-server-worker

   Expected result: each status command ends with successfully rolled out.

5. Confirm the new level in the API server log:

   kubectl -n foundation4ai logs deploy/foundation4ai-api-server -c server | grep "API on 0.0.0.0:8000"

   Expected result: a line that ends with Starting Foundation4.ai API on 0.0.0.0:8000. The line appears at level info and below, not at warn.

The operator removes the entry and repeats steps 2 and 4 when the diagnosis ends.

Logging

app.log_level sets the level of the API server and worker processes. The chart default is warn, and a production deployment keeps warn outside a limited diagnosis period, as described in Security hardening. The sample values file supplied with the charts sets debug, which is not a production value.

Process	Output	Level
API server	Standard output, text lines with timestamp, level and source	app.log_level. The database library logs at debug or trace only when app.log_level is debug or trace, and at warn otherwise. The h2, hyper_util and tower::buffer libraries are silenced, and the NATS client logs at warn.
Worker	Standard output, text lines with timestamp, level and source	app.log_level, for every library
gRPC service	Standard error	INFO, fixed
Dashboard	Container output	Not configurable

The RUST_LOG variable has no effect: the API server and the worker set the log filter from app.log_level. Monitoring and logging describes how to read the logs.

OpenTelemetry

The API server exports traces and log records through the OpenTelemetry Protocol (OTLP) when an OTLP variable is set. The workers, the gRPC service and the dashboard export no OpenTelemetry data. No collector ships with the charts.

Variable	Effect
OTEL_EXPORTER_OTLP_ENDPOINT	Base URL of the collector for all signals
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	Collector URL for one signal, overriding the base URL
OTEL_EXPORTER_OTLP_PROTOCOL	grpc or http/protobuf. Without the variable, an endpoint that contains :4317 selects grpc, and any other endpoint selects http/protobuf.
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, OTEL_EXPORTER_OTLP_LOGS_PROTOCOL	Protocol for one signal
OTEL_EXPORTER_OTLP_HEADERS	Headers sent to the collector, such as an authorization header
OTEL_EXPORTER_OTLP_TIMEOUT	Export timeout, in milliseconds
OTEL_SERVICE_NAME	Service name of the exported data. The default is foundation4ai.
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG	Sampling of traces, such as parentbased_traceidratio with a ratio
OTEL_PROPAGATORS	Trace context formats read from and written to HTTP headers. The default is tracecontext,baggage.

Without any endpoint or protocol variable, the API server creates no exporter and sends nothing. The build does not include the TLS option of the gRPC exporter, so a collector reached over gRPC uses an unencrypted connection. Metrics stay on the Prometheus endpoints described in Monitoring and logging, which also shows how to set the variables through configs.

Branding

branding.name sets the product name that the API server shows in the API documentation. The default is Foundation4.ai.

Location	Effect of branding.name
OpenAPI document /openapi.json, and the documentation pages /docs, /_docs and /_docs-swagger	The document title is the name, and the description is the name followed by API documentation
API server start log line	Starting <name> API on <address>, at level info
Dashboard	Not used; the dashboard shows the default name
Worker log, the response of /, the MCP server instructions and the OpenAPI section descriptions	Not used; the default name is fixed in the code

The following procedure sets the name. The example shows the default name; a deployment replaces the value.

1. Add the file to the values file of the application release:

   api-server:
     configs:
       f4ai-10-branding.yaml: |
         branding:
           name: Foundation4.ai

   Expected result: configs holds f4ai-10-branding.yaml.

2. Upgrade the application release and restart the API server:

   helm upgrade --install foundation4ai ./charts/foundation4ai \
     -n foundation4ai -f foundation4ai.values.yaml --wait --timeout 10m
   kubectl -n foundation4ai rollout restart deploy/foundation4ai-api-server
   kubectl -n foundation4ai rollout status deploy/foundation4ai-api-server

   Expected result: Helm reports STATUS: deployed, and the status command ends with successfully rolled out.

3. Read the title of the OpenAPI document through the port forward of API and dashboard access:

   curl -s "$FOUNDATION4_URL/openapi.json" | grep -o '"title":"[^"]*"' | head -1

   Expected result: "title":"Foundation4.ai", or the name that the file sets.