Configuration

DeepFellow Server and DeepFellow Infra both split their configuration into two kinds:

• Bootstrap settings load from .env at startup only. Changing one requires a restart.
• Dynamic settings live in config.json. On first boot, if config.json does not exist yet, the app seeds it from any matching .env values, then stops reading .env for those settings. From that point on, change them through the web panel, the CLI, or the /admin/config API, without a restart.

Every entry below names the .env variable first. For a dynamic setting, the name in parentheses is the path inside the settings object of config.json. For example, infra.url refers to the following:

{
    "settings": {
        "infra": {
            "url": "http://127.0.0.1:8086"
        }
    }
}

For details on where each file lives and how to edit it, read Server Configuration and Infra Configuration.

DeepFellow Server

Bootstrap Settings

These load from .env at startup. Set them with deepfellow server env set and restart the server.

• DF_MONGO_URL: MongoDB connection host and port. Default mongo:27017, the bundled MongoDB container.
• DF_MONGO_USER: MongoDB username. Generated at install.
• DF_MONGO_PASSWORD: MongoDB password. Generated at install.
• DF_MONGO_DB: Name of the MongoDB database the server uses. Default deepfellow.
• DF_FILESTORAGE_TARGET_PATH: Directory that holds uploaded files and config.json. Default storage/.
• DF_FILESTORAGE_META_PATH: Directory that holds file metadata. Default storage/.
• DF_FILESTORAGE_TEMP_PATH: Directory that holds uploads still in progress. Default storage/tmp.
• DF_PLUGINS_PATH: Directory the server scans for plugins. Default plugins.
• DF_RABBITMQ_ENABLED: Set to true to publish background jobs to RabbitMQ. Default false.
• DF_RABBITMQ_URL: AMQP connection URL of the RabbitMQ broker. Default amqp://guest:guest@localhost:5672/.
• DF_RABBITMQ_CONNECT_TIMEOUT_SECONDS: Seconds the server waits for a RabbitMQ connection before it gives up. Default 10.
• DF_CONFIG_JSON_PATH: Full path to config.json, overriding the file storage location above. Default $DF_FILESTORAGE_TARGET_PATH/config.json.

Dynamic Settings

These seed from .env on first boot and live in config.json afterwards. Change them from the Server Configuration card, with deepfellow server config set, or through the /admin/config API.

• DF_SERVER_URL (server_url): Public HTTP URL of DeepFellow Server. Default http://localhost:8000, built from DF_SERVER_PORT.
• DF_INFRA__URL (infra.url): HTTP URL of the connected DeepFellow Infra instance. Default http://infra:8086.
• DF_INFRA__API_KEY (infra.api_key): API key the server uses to authenticate with DeepFellow Infra. The installer reads DF_INFRA_API_KEY from a local Infra installation, or prompts you for it.
• DF_CHAT_TRANSLATION_MODEL (chat_translation_model): Model that translates chat messages (e.g. when using audio endpoints). Default gemma3:1b.
• DF_EVALUATE_MODEL (evaluate_model): Model that scores answers in evaluation runs. Default gemma3:1b.
• DF_LOG_LEVEL (log_level): Log level of the server, for example INFO or DEBUG. Default INFO.
• DF_ONLY_ADMIN_CAN_CREATE_ACCOUNTS_BY_INVITATION (only_admin_can_create_accounts_by_invitation): Set to true to let only an admin send account-creating invitations. Default true.
• DF_PLUGINS_SETUP (plugins_setup): JSON object passed to the plugins, for example {"df_abuse_model": "qwen3:1.7b"}. Default {}.
• DF_METRICS_USERNAME (metrics_username): Username that protects the /metrics endpoint. Generated at install.
• DF_METRICS_PASSWORD (metrics_password): Password that protects the /metrics endpoint. Generated at install.

Vector Database

The installer manages a Qdrant instance and turns the integration on unless you decline it.

• DF_VECTOR_DATABASE__PROVIDER__ACTIVE (vector_database.provider.active): Set to true to enable the vector database integration. Default true.
• DF_VECTOR_DATABASE__PROVIDER__TYPE (vector_database.provider.type): Vector database provider, either qdrant or milvus. Default qdrant.
• DF_VECTOR_DATABASE__PROVIDER__URL (vector_database.provider.url): URL of the vector database service. Default http://qdrant:6333, the bundled Qdrant container. With Milvus the installer writes http://milvus:19530.
• DF_VECTOR_DATABASE__PROVIDER__DB (vector_database.provider.db): Name of the database inside the vector database service. Default default. Milvus is the only provider the installer names a database for, and it writes deepfellow.
• DF_VECTOR_DATABASE__PROVIDER__USER (vector_database.provider.user): Username used for vector database authentication. Generated at install.
• DF_VECTOR_DATABASE__PROVIDER__PASSWORD (vector_database.provider.password): Password used for vector database authentication. Generated at install.
• DF_VECTOR_DATABASE__EMBEDDING__ACTIVE (vector_database.embedding.active): Set to true to embed documents when you add them to a vector store. Default true.
• DF_VECTOR_DATABASE__EMBEDDING__MODEL (vector_database.embedding.model): Embedding model used to generate vectors. Default mxbai-embed-large. Choosing sparse embeddings at install writes deepfellow-bge-m3 instead.
• DF_VECTOR_DATABASE__EMBEDDING__SIZE (vector_database.embedding.size): Number of dimensions of the embedding vectors. It has to match what your embedding model returns, and it sets the dimension of the collection the server creates. Changing it once documents are indexed means rebuilding the vector store. Default 1024.
• DF_VECTOR_DATABASE__EMBEDDING__SPARSE (vector_database.embedding.sparse): Set to true to store sparse vectors next to the dense ones. Default false.
• DF_VECTOR_DATABASE__RERANKER__ACTIVE (vector_database.reranker.active): Set to true to rerank search results before returning them. Default false.
• DF_VECTOR_DATABASE__RERANKER__MODEL (vector_database.reranker.model): Reranker model. Default BAAI/bge-reranker-v2-m3.
• DF_VECTOR_DATABASE__RERANKER__OVERSAMPLING (vector_database.reranker.oversampling): Multiplier applied to max_num_results to size the reranking candidate pool. A higher value hands the reranker more candidates, which improves recall and costs one larger vector search plus more reranking work per query. Default 2.5.
• DF_VECTOR_DATABASE__RERANKER__MIN_FETCH_K (vector_database.reranker.min_fetch_k): Smallest candidate pool the reranker will fetch, whatever the oversampling gives. It decides the pool size whenever max_num_results is small, so raising it makes every search fetch at least this many candidates. Default 50.
• DF_VECTOR_DATABASE__SEARCH__DEFAULT_NUM_RESULTS (vector_database.search.default_num_results): Number of results a search returns when the request does not ask for a count. It affects only how much a caller gets back, not how much work the search does. Default 5.
• DF_VECTOR_DATABASE__SEARCH__MAX_NUM_RESULTS (vector_database.search.max_num_results): Largest number of results a single search returns. With a reranker active it also sizes the candidate pool, so raising it multiplies the cost of every search, not just the size of the answer. Default 20.
• DF_VECTOR_DATABASE__VECTOR_THRESHOLD (vector_database.vector_threshold): Smallest similarity score a match needs to appear in the results. Raising it returns fewer but closer matches, and set too high it returns nothing at all. Default 0.3.
• DF_EMBEDDING_WORKER_COUNT (embedding_worker_count): Number of parallel workers that generate embeddings. Each worker keeps one request open against the embedding model served by DeepFellow Infra. Raise it only as far as that model answers requests in parallel, since the server itself spends the time waiting. Default 5.
• DF_EMBEDDING_BATCH_SIZE (embedding_batch_size): Number of chunks sent to the embedding model in one request. The bigger the number the more context of the embedding model is used. Default 10.
• DF_RERANKER_WORKER_COUNT (reranker_worker_count): Number of parallel workers that rerank results. Each worker keeps one request open against the reranker model. Anything above what that model answers in parallel simply waits in a queue there. Default 5.

Document Processing

• DF_DOC_CHUNKER_USE (doc_chunker_use): Set to true to send files to Doc Chunker when you add them to a vector store. Set to false to keep the built-in text extraction. Default true.
• DF_DOC_CHUNKER_PREFIX (doc_chunker_prefix): Endpoint prefix the server uses to reach Doc Chunker. It matches the prefix you set when you installed the service. Default doc_chunker.
• DF_DOC_CHUNKER_PICTURE_DESCRIPTION_MODEL (doc_chunker_picture_description_model): Vision model that describes images found inside documents. Default granite3.2-vision:2b.
• DF_LEMMATIZER_ENDPOINT_PREFIX (lemmatizer_endpoint_prefix): Endpoint prefix the server uses to reach the lemmatizer service. Default lemmatizer.
• DF_LEMMATIZER_WORKER_COUNT (lemmatizer_worker_count): Number of parallel workers that lemmatize text. Each worker keeps one request open against the lemmatizer service, whose own capacity decides how far raising this helps. Default 5.
• DF_METADATA_EXPANSION_QUEUE_NAME (metadata_expansion_queue_name): Name of the RabbitMQ queue that carries metadata expansion jobs. Default metadata_expansion.
• DF_METADATA_EXPANSION_MODEL (metadata_expansion_model): Model that expands document metadata. Default gemma3:1b.
• DF_METADATA_EXPANSION_MAX_ATTEMPTS (metadata_expansion_max_attempts): Number of times a metadata expansion job retries before it fails. It is also the queue's delivery limit. A higher value lets a job survive a model that is unavailable for a few minutes, and it also spends that many model calls on a job that will never succeed. Default 3.

Email

The installer configures no mail server, so invitation emails stay off until you set these. Read Configure Email for Invitations for the full setup.

• DF_SMTP__HOST (smtp.host): Hostname of the SMTP server that sends invitation emails. Default localhost.
• DF_SMTP__PORT (smtp.port): Port of the SMTP server. Default 25.
• DF_SMTP__AUTH (smtp.auth): Set to true to authenticate with the SMTP server. Default false.
• DF_SMTP__USER (smtp.user): SMTP username. Default empty.
• DF_SMTP__PASSWORD (smtp.password): SMTP password. Default empty.
• DF_SMTP__EMAIL_FROM (smtp.email_from): Address that appears in the From header of sent emails. Default no-reply@domain.com.
• DF_SMTP__USE_TLS (smtp.use_tls): Set to true to connect to the SMTP server over TLS. Default false.

Fine-tuning, MCP, and Telemetry

• DF_FINE_TUNING_POLL_INTERVAL_SECONDS (fine_tuning_poll_interval_seconds): Seconds between two polls of a fine-tuning worker. A shorter interval reports job progress sooner and sends proportionally more requests to every worker. Default 60.
• DF_FINE_TUNING_MAX_WORKER_SYNC_FAILURES (fine_tuning_max_worker_sync_failures): Consecutive failed polls, counted per job, after which the server marks that job failed. A higher value survives a worker that restarts mid-training, and it also leaves a genuinely dead job running for this many poll intervals before anyone finds out. Default 5.
• DF_MCP_SESSION_TTL_SECONDS (mcp_session_ttl_seconds): Seconds an idle pooled MCP session stays alive. A longer TTL reuses the connection to the MCP server instead of repeating the handshake, at the cost of holding idle connections open. Default 300.
• DF_MCP_SESSION_SWEEP_INTERVAL_SECONDS (mcp_session_sweep_interval_seconds): Seconds between two sweeps that close expired MCP sessions. An expired session survives until the next sweep, so its real lifetime is the TTL plus up to this much. Default 60.
• DF_OTEL_EXPORTER_OTLP_ENDPOINT (otel_exporter_otlp_endpoint): OTLP endpoint that receives traces and logs. Default http://localhost:4317. Letting the installer run a local collector writes http://otel-collector:4317.
• DF_OTEL_TRACING_ENABLED (otel_tracing_enabled): Set to true to export traces over OTLP. Default false. The installer sets true whenever it configures OpenTelemetry.
• DF_OTEL_LOGGING_ENABLED (otel_logging_enabled): Set to true to export logs over OTLP. Default false.

Deployment Variables

Docker Compose reads these from the same .env file, but the server itself never reads them. Changing one requires deepfellow server restart.

• DF_SERVER_PORT: Host port the server container publishes. Default 8000.
• DF_SERVER_IMAGE: Docker image that runs DeepFellow Server. Default hub.simplito.com/deepfellow/deepfellow-server at the newest tag the installer finds.
• DF_MONGO_PORT: Host port the bundled MongoDB container publishes. Default 27017.
• DF_MONGO_INITDB_ROOT_USERNAME: Root user the bundled MongoDB container is initialized with. Generated at install.
• DF_MONGO_INITDB_ROOT_PASSWORD: Password of that root user. Generated at install.
• DF_INFRA_DOCKER_SUBNET: Docker network the server shares with the infrastructure services. Default deepfellow-infra-net.

DeepFellow Infra

Bootstrap Settings

These load from .env at startup. Set them with deepfellow infra env set and restart Infra.

• DF_INFRA_ADMIN_API_KEY: Key used for DeepFellow Infra administration: changing configuration, installing services and models, and reading logs. Generated at install, as a UUID.
• DF_INFRA_DOCKER_SUBNET: Docker network Infra attaches the service containers to. Reaches the container as DF_DOCKER_SUBNET. Default deepfellow-infra-net.
• DF_INFRA_STORAGE_DIR: Directory that holds Infra persistent storage and config.json. Reaches the container as DF_STORAGE_DIR. Default ~/.deepfellow/infra/storage.
• DF_INFRA_COMPOSE_PREFIX: Prefix of the Docker Compose resources Infra generates. Reaches the container as DF_COMPOSE_PREFIX. Generated at install as df followed by six random characters and an underscore, for example df7k2m9x_.
• DF_STORAGE_SERVICES_DIR: Directory that holds per-service state. Default $DF_STORAGE_DIR/services.
• DF_CONTAINER_NAME_PREFIX: Prefix of the names Infra gives the service containers. Default empty.
• DF_DOCKER_HUB_TOKEN: Docker Hub token used to pull images that need authentication. Default empty.
• OLLAMA_KV_CACHE_TYPE: Quantization of the Ollama key-value cache, for example f16 or q8_0. Default f16.
• OLLAMA_NUM_PARALLEL: Number of requests Ollama serves in parallel. A value below 1 is clamped to 1. Infra treats it as the capacity of each Ollama instance, so raising it sends more requests to one instance before Infra moves them to another, and it also raises the estimated VRAM a model needs, because each parallel slot holds its own key-value cache. Default 1.
• OLLAMA_VRAM_OVERHEAD_FACTOR: Multiplier applied to the estimated VRAM need of a model before Infra places it on a GPU. Above 1 it reserves headroom and fits fewer models on a card, below 1 it risks committing more VRAM than the card has. Default 1.0.

Two more variables exist for debugging only. The installer never writes them. Infra reads each one once at startup, so restart Infra after you change either.

• DF_DEBUG_FORCE_NO_GPU: Set to true to make Infra behave as if the host had no supported GPU. Default unset.
• DF_DEBUG_FORCE_NO_AVX512: Set to true to make Infra behave as if the host CPU lacked AVX-512. Default unset.

Dynamic Settings

These seed from .env on first boot and live in config.json afterwards. Change them from the Configuration page of the Infra Web Panel or through the /admin/config API.

• DF_NAME (name): Name of this Infra node, shown in the panel and across a mesh. Default infra.
• DF_INFRA_URL (infra_url): Base HTTP URL other containers use to reach this Infra. Default http://infra:8086.
• DF_INFRA_API_KEY (infra_api_key): Key that authorizes calls to the /v1/ endpoints and to GET /info. Generated at install, as a UUID.
• DF_MESH_KEY (mesh_key): Key another Infra presents to connect to this node over WebSocket. Generated at install, as a UUID.
• DF_CONNECT_TO_MESH_URL (connect_to_mesh_url): WebSocket URL of the parent Infra this node connects to, which is the parent's DF_INFRA_MESH_URL. Default empty. deepfellow infra connect fills it in.
• DF_CONNECT_TO_MESH_KEY (connect_to_mesh_key): Key this node presents to the parent Infra, which is the parent's DF_MESH_KEY. Default empty. deepfellow infra connect fills it in.
• DF_SHARE_MODELS_DOWNSTREAM (share_models_downstream): Set to true to expose this node's models, and its ancestors' models, to connecting nodes. Default true.
• DF_HUGGING_FACE_TOKEN (hugging_face_token): Hugging Face token used to download gated models. Default empty. The installer writes it only when you supply one.
• DF_CIVITAI_TOKEN (civitai_token): CivitAI token used to download image-generation models. Default empty. The installer writes it only when you supply one.
• DF_ADAPTER_REGISTRY_URL (adapter_registry_url): URL of the registry that serves fine-tuned adapters. Default empty.
• DF_ADAPTER_REGISTRY_SECRET (adapter_registry_secret): Secret used to authenticate with the adapter registry. Default empty.
• DF_LOG_PAYLOADS (log_payloads): Set to true to log full request and response payloads. Default empty, treated as false.
• DF_STOP_CONTAINERS_ON_SHUTDOWN (stop_containers_on_shutdown): Set to false to leave the service containers running when Infra stops. Default empty, treated as true.
• DF_STANDARD_PROXY_TIMEOUT_SECONDS (standard_proxy_timeout_seconds): Timeout of outbound proxy requests to the model and tool services: a cap on the whole call for chat completions, embeddings, audio, images, and reranking, and an idle-read window between chunks for a custom service. Set too low it cuts off a long generation that was still producing output. Override it per service with the proxy_timeout_seconds install field. Default 600.
• DF_MCP_SSE_SESSION_TTL_SECONDS (mcp_sse_session_ttl_seconds): Seconds an idle MCP SSE session stays alive. A client quiet for longer than this has to open a new session. Default 300.
• DF_MCP_SSE_MAX_SESSIONS (mcp_sse_max_sessions): Largest number of MCP SSE sessions Infra keeps open at once. At capacity Infra drops the oldest session to admit a new one, so a value below your real number of concurrent clients disconnects sessions that are still in use. Default 128.
• DF_METRICS_USERNAME (metrics_username): Username that protects the /metrics endpoint. Generated at install.
• DF_METRICS_PASSWORD (metrics_password): Password that protects the /metrics endpoint. Generated at install.
• DF_OTEL_EXPORTER_OTLP_ENDPOINT (otel_exporter_otlp_endpoint): OTLP endpoint that receives traces and logs. Default http://localhost:4317.
• DF_OTEL_TRACING_ENABLED (otel_tracing_enabled): Set to true to export traces over OTLP. Default false.
• DF_OTEL_LOGGING_ENABLED (otel_logging_enabled): Set to true to export logs over OTLP. Default false.

Deployment Variables

Docker Compose reads these from the same .env file, but Infra itself never reads them. Changing one requires deepfellow infra restart.

• DF_INFRA_PORT: Host port the Infra container publishes. Default 8086.
• DF_INFRA_IMAGE: Docker image that runs DeepFellow Infra. Default hub.simplito.com/deepfellow/deepfellow-infra at the newest tag the installer finds.
• DF_INFRA_DOCKER_CONFIG: Path to the Docker client configuration file mounted into Infra. Default ~/.deepfellow/infra/docker-config.json, created empty when it does not exist.

Derived Values

deepfellow infra info and deepfellow infra env info print one more key that no file holds. Infra computes it on every run, so setting it in .env changes nothing.

• DF_INFRA_MESH_URL: WebSocket address other Infras use to reach this node over a Mesh. Derived from DF_INFRA_URL by swapping the scheme: http:// becomes ws://, https:// becomes wss://. With the installer's default DF_INFRA_URL the result is ws://infra:8086.

To attach a child Infra to a parent, read the parent's DF_INFRA_MESH_URL and DF_MESH_KEY, then pass both to deepfellow infra connect on the child:

deepfellow infra connect ws://PARENT_HOST:8086 PARENT_MESH_KEY

The command accepts an http:// address too and converts the scheme itself. It stores the pair as the child's connect_to_mesh_url and connect_to_mesh_key through the /admin/config API, which makes them dynamic settings rather than .env entries.

Read Connect More Infras for the full procedure.