Configuration

Reference of every DeepFellow Server and DeepFellow Infra configuration variable.

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.

The defaults below are the values in place after an install with the deepfellow CLI. Where the installer generates a secret, the entry says "Generated at install" instead of naming a value. Where the installer writes nothing into .env, the value is the application's own fallback, which is what the install leaves in place.

Addresses such as mongo:27017, http://qdrant:6333, and http://infra:8086 are Docker service names. They resolve from inside the DeepFellow Docker network, where every component runs, and not from your shell on the host.

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_URL: AMQP connection URL that seeds the rabbitmq section on any boot where that section is not configured yet. Once the section is saved, the server ignores it and logs a warning at boot if it names a different broker. In .env the installer writes only the host and port, rabbitmq:5672, and Docker Compose builds the full URL from them, DF_RABBITMQ_USER, and DF_RABBITMQ_PASSWORD. Set a different host and port with --rabbitmq-url on deepfellow server install.
DF_RABBITMQ_CONNECT_TIMEOUT_SECONDS: Seeds rabbitmq.connect_timeout_seconds together with DF_RABBITMQ_URL. Once the section is saved, the server ignores it. Default 10.
DF_NIGHTSHIFT_CONFIG_POLL_INTERVAL_SECONDS: Seconds between two checks of config.json by the Nightshift worker. See Configuration Reload. Default 5.
DF_NIGHTSHIFT_RELOAD_DRAIN_TIMEOUT_SECONDS: Seconds the Nightshift worker waits for messages in progress to finish before it restarts on a configuration change or stops. Keep the worker container's stop timeout above it. See Stop the Worker. Default 300.
DF_NIGHTSHIFT_METRICS_PORT: Port of the Nightshift worker's Prometheus /metrics endpoint, from 1 to 65535. 0 is replaced with 9464, and the worker logs a warning. See Monitoring. Default 9464.
DF_NIGHTSHIFT_METRICS_HOST: Address the Nightshift worker's /metrics endpoint listens on. The installer sets 0.0.0.0 on the nightshift container, so the endpoint is reachable on the Docker network but not published on the host. Default 127.0.0.1 outside the installer's Docker setup.
DF_NIGHTSHIFT_METRICS_URL: Address DeepFellow Server fetches the Nightshift worker's metrics from, to serve them on its own /metrics endpoint. An empty value turns this off. See Nightshift Metrics. Default http://nightshift:9464/metrics.
DF_VECTOR_STORE_FILE_PROCESSING_MAX_ATTEMPTS: Number of attempts Nightshift gives a file it adds to a vector store before the file fails. Default 5.
DF_VECTOR_STORE_MIGRATION_MAX_ATTEMPTS: Number of attempts Nightshift gives a file it re-embeds during a vector store migration before the file fails. Default 5.
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. With a DF_SERVER_BIND_ADDRESS set at install, the installer puts that address in place of localhost, for example http://127.0.0.1:8000.
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_INFRA__ADMIN_API_KEY (infra.admin_api_key): DeepFellow Infra's admin key, which the server uses to install the versions fine-tuning pipelines promote. Pipelines are disabled while it is empty. The variable only seeds a new install; on an existing install, set it with deepfellow server config set. Default empty.
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", "ti_fail_open": "false"}. Every value is a string or a list of strings. It also carries the Threat Intelligence keys: ti_url and ti_fail_open, which both guards share, and ti_input_workflow_name and ti_output_workflow_name, one per guard. The guards' API key lives outside this object, in ti_api_key below. Default {}.
ti_api_key: API key the two Threat Intelligence guards, df_ti_input_guard and df_ti_output_guard, use to authenticate with the Threat Intelligence service. Both guards share it. It has no .env equivalent, so set it from the Server Configuration card or with PUT /admin/config. When it is empty, the guards fall back to the TI_API_KEY environment variable, which each guard's own configuration file names in ti_api_key_env. Default empty. See Threat Intelligence Guards.
DF_RABBITMQ_URL (rabbitmq.*): AMQP connection URL of the RabbitMQ broker. On any boot where the rabbitmq section is not configured yet, the server splits it into that section of config.json: rabbitmq.host, rabbitmq.port, rabbitmq.username, rabbitmq.password, rabbitmq.vhost, and rabbitmq.ssl. Defaults localhost, 5672, guest, guest, /, and false. See RabbitMQ Connection.
DF_RABBITMQ_CONNECT_TIMEOUT_SECONDS (rabbitmq.connect_timeout_seconds): Seconds the server waits for a RabbitMQ connection before it gives up. Default 10.
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_MAX_CONCURRENT_REQUESTS (max_concurrent_requests): Maximum concurrent requests the server declares it can handle, reported in the X-Max-Concurrent-Requests response header and in GET /info for external monitoring and autoscaling. Informational only. The server does not enforce it. Default 100. The server also reports how much of that limit is free at any moment: the difference between max_concurrent_requests and the number of requests it is currently processing, exposed as the X-Available-Capacity response header and the available_capacity field of GET /info.

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.
DF_VECTOR_STORE_EXPIRY_SWEEP_INTERVAL_SECONDS (vector_store_expiry_sweep_interval_seconds): Seconds between two sweeps that delete vector stores past their expires_after policy, at least 1. An expired store survives until the next sweep, though requests reject it as soon as it expires. Default 300.

Document Processing

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 gemma4:e4b (the chat model installed by suite install, which also handles images).
DF_DOC_CHUNKER_STT_MODEL (doc_chunker_stt_model): Speech-to-text model Doc Chunker uses to transcribe audio and video files. Default Systran/faster-whisper-large-v3.
DF_DOC_CHUNKER_CONVERT_TIMEOUT_SECONDS (doc_chunker_convert_timeout_seconds): Seconds the server waits for one Doc Chunker conversion, including the time the file waits in Doc Chunker's queue. Keep it below nightshift_jobs_timeout_seconds. For a Doc Chunker image without the job API, also keep it no higher than the proxy_timeout_seconds of the doc_chunker install on DeepFellow Infra. See Conversion Timeouts. Default 7200.
DF_DOC_CHUNKER_POLL_INTERVAL_SECONDS (doc_chunker_poll_interval_seconds): Seconds between two reads of a Doc Chunker conversion job's status. Default 5.
DF_DOC_CHUNKER_REQUEST_TIMEOUT_SECONDS (doc_chunker_request_timeout_seconds): Seconds one file upload to Doc Chunker or one result download takes at most. It does not limit the conversion, which doc_chunker_convert_timeout_seconds caps. Default 300.
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_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.
DF_METADATA_EXPANSION_CONCURRENCY (metadata_expansion_concurrency): Number of documents each Nightshift worker expands at once, from 1 to 64. Default 4.

Document Summarization

These configure Document Summarization.

DF_SUMMARIZATION_MODEL (summarization_model): Model that writes document summaries. Default gemma4:12b. An existing install keeps the model stored in its config.json.
DF_SUMMARIZATION_MAX_ATTEMPTS (summarization_max_attempts): Number of attempts a document gets before it is marked failed. It is also the queue's delivery limit. Default 3.
DF_SUMMARIZATION_CONCURRENCY (summarization_concurrency): Number of documents each Nightshift worker summarizes at once, from 1 to 64. Default 4.

Nightshift and RabbitMQ

These configure Nightshift Background Jobs and its connection to RabbitMQ.

DF_NIGHTSHIFT_JOBS_TIMEOUT_SECONDS (nightshift_jobs_timeout_seconds): Maximum time, at least 1 second, a single document's extraction or summarization step runs before it counts as a failed attempt. It includes the time a document waits behind the others a worker processes at once, so raise it when you raise metadata_expansion_concurrency or summarization_concurrency. It has to stay above doc_chunker_convert_timeout_seconds, and PUT /admin/config rejects a value that does not. See Job Timeouts. Default 10800.

The rabbitmq section holds the RabbitMQ connection. It has no .env variables. The server seeds it from DF_RABBITMQ_URL and DF_RABBITMQ_CONNECT_TIMEOUT_SECONDS on any boot where it is not configured yet, which means missing from config.json or equal to the built-in defaults. The seed drops any query parameters in the URL. Until DF_RABBITMQ_URL is set, the built-in defaults apply without being written to config.json. After a non-default section is saved, it behaves like any other dynamic setting, with one exception: while DF_RABBITMQ_URL names a broker other than the defaults, a change that sets the section back to the defaults returns 400 Bad Request. See RabbitMQ Connection.

rabbitmq.host: Hostname of the RabbitMQ broker. Default rabbitmq, the bundled RabbitMQ container.
rabbitmq.port: Port of the RabbitMQ broker, from 1 to 65535. Default 5672, or 5671 for an amqps:// URL.
rabbitmq.username: RabbitMQ username. Generated at install, as DF_RABBITMQ_USER.
rabbitmq.password: RabbitMQ password. Generated at install, as DF_RABBITMQ_PASSWORD.
rabbitmq.vhost: RabbitMQ virtual host. Default /.
rabbitmq.ssl: Set to true to connect to RabbitMQ over TLS. Default false, or true for an amqps:// URL.
rabbitmq.connect_timeout_seconds: Seconds the server waits for one RabbitMQ connection attempt, greater than 0. Default 10.

Knowledge Graph

The graph section configures Knowledge Graph: the FalkorDB connection, the models used for extraction and answers, and ontology discovery. Its settings follow the DF_GRAPH__FIELD (graph.field) pattern, for example DF_GRAPH__ENABLED (graph.enabled). The installer sets DF_GRAPH__ENABLED, DF_GRAPH__HOST, DF_GRAPH__PORT, and DF_GRAPH__PASSWORD when you pass --falkordb-active. For every setting and its default, see Knowledge Graph Settings.

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.
finetune_pipelines: Settings of fine-tuning pipelines, such as the generation and judge models and the number of runs in progress at once. It has no .env equivalent, so set it with deepfellow server config set or PUT /admin/config. The Server Configuration card doesn't show it.
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.
sentry_enabled: Set to true to report unhandled exceptions and errors to Sentry. It has no .env equivalent, like the other two Sentry settings, so set it from the Server Configuration card or with PUT /admin/config. Default false.
sentry_dsn: DSN of the Sentry project that receives the events, on Sentry SaaS or a self-hosted instance. Masked like other credentials. Default empty.
sentry_environment: Environment tag attached to every Sentry event. Default empty, reported as production.

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_BIND_ADDRESS: Host address the server container publishes DF_SERVER_PORT on, for example 127.0.0.1. An IPv6 address goes in brackets, for example [::1], which deepfellow server env set adds for you. An empty value publishes the port on all interfaces. Set it with --bind-address on deepfellow server install. Default empty. See Published Ports.
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 on DF_INTERNAL_BIND_ADDRESS. Default 27017.
DF_INTERNAL_BIND_ADDRESS: Host address the bundled MongoDB container publishes its port on. The same address applies to every port that --dev publishes. An IPv6 address goes in brackets, for example [::1], which deepfellow server env set adds for you. An empty value publishes the ports on all interfaces. The installer doesn't write it. deepfellow server update sets it to an empty value if you decline moving the ports of an older install to 127.0.0.1. See Published Ports. Default unset, which means 127.0.0.1.
DF_MONGO_INITDB_ROOT_USERNAME: Root user the bundled MongoDB container is initialized with. Generated at install. On an install where deepfellow server update switched the server to a dedicated account, it holds the previous value of DF_MONGO_USER. See MongoDB Account.
DF_MONGO_INITDB_ROOT_PASSWORD: Password of that root user. Generated at install. On an install where deepfellow server update switched the server to a dedicated account, it holds the previous value of DF_MONGO_PASSWORD.
DF_INFRA_DOCKER_SUBNET: Docker network the server shares with the infrastructure services. Default deepfellow-infra-net.
DF_RABBITMQ_USER: RabbitMQ username Docker Compose puts into DF_RABBITMQ_URL. It also creates that user in the bundled RabbitMQ container. Generated at install for the bundled container, or prompted for when you connect to an existing instance.
DF_RABBITMQ_PASSWORD: Password of that RabbitMQ user. Generated at install for the bundled container, or prompted for when you connect to an existing instance.

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_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_CONTAINER_NAME_SUFFIX (container_name_suffix): Suffix Infra appends to each service container's name so two instances sharing a Docker host don't collide, for example _infra_a1b2c3. Infra generates one automatically at first boot, using only letters, digits, underscores, and hyphens; a change applies only to new installs and reinstalls, not already-running containers. Default: a random suffix generated at first boot.
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 and private models and to check access to them when you add a custom vLLM model. 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. A custom-service model that declares its own default, such as doc_chunker with 7200 seconds, uses that default instead. 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_BIND_ADDRESS: Host address the Infra container publishes DF_INFRA_PORT on, for example 127.0.0.1. An IPv6 address goes in brackets, for example [::1], which deepfellow infra env set adds for you. An empty value publishes the port on all interfaces. Set it with --bind-address on deepfellow infra install. Default empty. See Published Port.
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.

A parent address of localhost or 127.0.0.1 will fail. The child Infra runs inside Docker, where those addresses point at the container itself. Use host.docker.internal for a parent on the same machine, and the host's real address otherwise.

Read Connect More Infras for the full procedure.

On this page