Supported Settings — What You May Change

AI Knowledge Fabric starts several parts that must work together: the management app, its database, and the Topic, GraphRAG Topic and Agent containers it creates. Most settings are safe to change. A few are not, because another part depends on them. This page tells you which is which.

Use it before you change anything in the .env file, in the Compose file, or in the Kubernetes files.

The short version:

  • Change settings in the web UI whenever you can. The UI checks your input. Most of what you want to tune is there.

  • Outside the UI, change only the .env file (or the env: list on Kubernetes), and only the settings in the tables below marked Supported.

  • Never edit the Compose file or the Kubernetes files, except for the lines named here.

  • Change versions only together. See Versions.

1. The four levels

Level Meaning What you should do

Required

You must set it before you start. The defaults are known to everybody and are not safe

Set it once. Do not leave the default

Supported

Changing it is safe, and you can change it back

Change it when you need to

With care

It works, but a wrong value fails in a way that is hard to see, or it affects other parts

Change it only for the reason given in the table. Test afterwards

Not supported

Another part depends on it. A change can break the installation, lose data, or stop updates from working

Do not change it. Ask the support first

2. Settings

Names in the tables are the variable names you write in .env (Docker) or in the env: list of the aiknowledgefabric container (Kubernetes). Where Applies says restart the app, run docker compose up -d (Docker) or kubectl rollout restart deployment/aiknowledgefabric (Kubernetes).

2.1 Required — set them before the first start

Setting Default Why you must set it If you change it later

DB_PASSWORD

admin

The database holds all users, roles and configuration

Only works on the first start. Later, change the password inside PostgreSQL first, or the app cannot reach its database

METRICS_API_KEY

an example value

Containers send usage numbers with it. Without a private value, strangers can send fake numbers

Stop and start Topics and Agents afterwards

CYROCK_LICENSE_KEY

empty

Without a valid license nothing can be created or started. You can also enter the key under Admin → License

Reaches containers on their next start

Also change the password of the first account (admin / admin) under Profile → Change Password.

2.2 Supported — change freely

Setting Default What it does Higher / lower, on / off Applies

APP_PORT

8080

Port of the web UI on the host

—

Restart the app, then restart running Topics and Agents so they get the new address

SESSION_COOKIE_NAME

KFSESSIONID

Name of the login cookie

Change it only if another app on the same host name uses the same name

Restart the app. Users log in again

JWT_EXPIRY_HOURS

1

How long an issued token works

Higher: fewer logins, a stolen token or a removed role keeps working longer. Lower: safer, more logins

Restart the app

AUTH_LOGIN_MAX_FAILURES

5

Failed sign-ins for one account (login form, /api/auth/token) within AUTH_LOGIN_WINDOW (15m) that lock it for AUTH_LOGIN_LOCKOUT (15m); AUTH_LOGIN_MAX_FAILURES_PER_IP (50) does the same per client address

Counted per app instance. Behind a proxy the address is the proxy’s unless forwarded headers are configured

Restart the app

AUTH_MODE

form

Login method when the database has no setting yet. The effective mode is set in the UI

—

Restart the app

PIPELINE_SEED_EXAMPLES

true

Adds example pipelines on the very first start

Off: an empty pipeline list

First start only

API_DOCS_PUBLIC

true

Whether the API documentation opens without a login

Off: a login is needed

Restart the app

PASSWORD_RESET_TOKEN_TTL

60m

How long a "forgot password" link works

Higher: more time, longer risk. Lower: safer

Restart the app

MCP_GITHUB_TOKEN

empty

Raises the rate limit of the MCP tool catalog

—

Restart the app

RAG_SERVICE_STARTUP_TIMEOUT, GRAPHRAG_SERVICE_STARTUP_TIMEOUT, AGENT_SERVER_STARTUP_TIMEOUT

120 (seconds)

How long a start waits for a new Topic, GraphRAG Topic or Agent

Higher: slow hosts get time. Lower: a broken start shows sooner

Restart the app

AI_SERVER_STARTUP_TIMEOUT, DOCLING_STARTUP_TIMEOUT

90 (seconds)

The same for managed AI servers and Docling servers

As above

Restart the app

AI_SERVER_MODEL_LIST_REFRESH_INTERVAL

600 (seconds)

How often the model lists in the pickers update

Lower: new models show sooner, more requests to your AI servers

Restart the app

AI_SERVER_MODEL_LIST_INITIAL_DELAY, AI_SERVER_MODEL_LIST_TIMEOUT

15, 10 (seconds)

Delay of the first update, and how long one request may take

A higher timeout helps slow servers

Restart the app

2.3 With care — only for the reason given

Setting Default Change it only when What can go wrong

CONTAINER_FRONTEND_URL

host.docker.internal:<APP_PORT>;

Topics and Agents reach the app at another address than the published port

Topics and Agents refuse every token; the usage dashboard stays empty

TOPIC_PUBLIC_BASE_URL_PATTERN, GRAPHRAG_PUBLIC_BASE_URL_PATTERN, AGENT_PUBLIC_BASE_URL_PATTERN

empty

Other systems call Topics or Agents from outside. See Public Endpoints

Source links and API answers carry a wrong address. A change reaches a resource only after a stop and start

RAG_SERVICE_HOST, GRAPHRAG_SERVICE_HOST, AGENT_SERVICE_HOST, DOCLING_SERVICE_HOST

host.docker.internal (set in the Compose file)

The app cannot reach the host under this name

Topics show Running or Error wrongly. Uploads and chats fail

RAG_MCP_HOST, GRAPHRAG_MCP_HOST

host.docker.internal

The host name is not reachable for the containers

Topics cannot call each other as tools

RAG_AI_SERVER_HOST, GRAPHRAG_AI_SERVER_HOST, RAG_DOCLING_HOST, GRAPHRAG_DOCLING_HOST

host.docker.internal

Your AI or Docling server is registered with localhost, and host.docker.internal does not work. On Kubernetes this name does not exist: register real addresses instead

A Topic starts, but every upload and chat fails with a connection error. The value applies to every server registered with localhost

RAG_SERVICE_PULL_POLICY, GRAPHRAG_SERVICE_PULL_POLICY, AGENT_SERVER_PULL_POLICY

Always

You test an image you built yourself (Never)

With Never, a Topic never gets updates, and nobody sees it

*_IMAGE (the image names)

cyrockai/knowledge-fabric-…

You mirror the images into your own registry

The mirror must hold the exact same builds. A different build is not supported

DB_URL, DB_USERNAME

the database in the Compose file

You use your own PostgreSQL

It must be PostgreSQL 16, and the user needs full rights on its database. Another version is not supported

Kubernetes: K8S_*CPU*, K8S_*MEMORY*

see CPU and memory

A workload is too slow, or is stopped for lack of memory

A limit that is too low makes Kubernetes stop the pod: failed uploads and answers. A request that is too high leaves pods without a node

Kubernetes: KUBERNETES_*_SIZE

1Gi, 256Mi

A volume is too small for your data

Applies only to new volumes. An existing volume keeps its size

Kubernetes: KUBERNETES_STORAGE_CLASS

the cluster default

There is no default class, or you want a faster one

Applies only to new volumes. A wrong class leaves volumes Pending

Kubernetes: KUBERNETES_API_KEYS_SECRET

aiknowledgefabric-api-keys

You keep AI keys in a Secret with another name

A missing Secret or key starts the pod without the key. Model calls then fail

2.4 Not supported — do not change

Setting or part Why not

The image versions one by one (*_IMAGE_VERSION, the tag of the app image)

The app, Topic, GraphRAG and Agent images belong together. See Versions

The PostgreSQL version in the Compose file

A new major version cannot read the old data. The database does not start

DOCLING_SERVER_IMAGE

The app is tested with its own Docling version. Another version can read documents differently

Ollama image

Fixed in the app. There is no setting

COMPOSE_DIR, AGENT_COMPOSE_DIR, GRAPHRAG_COMPOSE_DIR

They must stay on the volume compose-files. Elsewhere, the files vanish when the container is created again, and running resources can no longer be stopped

PORT (the port inside the container)

The Compose file and the Kubernetes Service expect 8080

RAG_FILE_DOWNLOAD_TOKEN_TTL, GRAPHRAG_FILE_DOWNLOAD_TOKEN_TTL

The Topic containers have their own matching value. If the two differ, source links show as valid when they are not

ORCHESTRATION_MODE, KUBERNETES_NAMESPACE after installation

Everything the app created stays in the old place. The app no longer finds it

The Docker socket mount, volume names, container names, the internal network

Stop, delete and update depend on them

Anything in the Compose or Kubernetes files that this page does not name

Not tested

3. Versions

The app image, the Topic image, the GraphRAG image and the Agent image belong together. They must have the same major version. A change in the app can need a matching change in an image.

By default all four use the same floating tag 1, the current major version. They stay together, and pull_policy: always brings in the newest release when a container is created. That is the supported way.

If you need a fixed version (for example for a maintenance window):

  1. Choose one release and use the version numbers that belong to it. Ask your contact at Cyrock for them.

  2. Set all four images to it: the app image in the Compose or Kubernetes file, and RAG_SERVICE_IMAGE_VERSION, GRAPHRAG_SERVICE_IMAGE_VERSION, AGENT_SERVER_IMAGE_VERSION.

  3. Update them together, and then stop and start your Topics, GraphRAG Topics and Agents.

Never change one version and leave the others. A mix of versions is not supported.

4. Changing settings safely

  1. Take a backup of the database first (Backup).

  2. Change one thing at a time, so you know which change caused a problem.

  3. Docker: check the result without starting it: docker compose config. Then apply it with docker compose up -d. A plain docker compose restart does not read .env again.

  4. Kubernetes: change the env: list or the Secret, then restart the deployment.

  5. Restart what needs it. A setting that is written into containers (license key, public address, metrics) reaches a running Topic or Agent only after you stop and start it in the UI.

  6. Test with one upload and one chat question.

  7. Keep the old .env. To go back, restore it and run the same command again.

A sensible starting .env

# Required
DB_PASSWORD=<strong password, set before the first start>
METRICS_API_KEY=<random string>
CYROCK_LICENSE_KEY=<your key, or enter it later under Admin → License>

# Only if you need them
# APP_PORT=8080
# CONTAINER_FRONTEND_URL=http://host.docker.internal:8080   (follows APP_PORT by default)

Everything else can stay at its default.

5. What you set in the web UI instead

Most behavior is set in the UI, with checks on your input, and does not need a restart of the app:

What Where

Models, servers, vector and graph databases

Admin → AI Servers, Docling Servers, Vector Databases, Graph Databases

Prompts and the shared system prompt

Admin → LLM Configuration, Prompt Templates, and the Prompts tab of a Topic

Public addresses

Admin → Public Endpoints

Users, roles, single sign-on

Admin → User Management, Roles & Permissions, OIDC Settings

E-mail (password reset)

Admin → Mail Server, Mail Templates

License

Admin → License

Ports, resources and access of one Topic or Agent

The resource’s Configuration tab

Related