Amgix Configuration

Environmental Variables

Amgix containers are configured by setting environment variables. The table below lists the possible settings. Yes in the last three columns means that service uses the variable.

Variable	Description	Values	Default	Amgix API	Amgix Encoder	Amgix One
AMGIX_DATABASE_URL	Storage backend connection URI.	qdrant://…, mariadb://…, postgresql://… (see Database Backends)	Must be set for API and Encoder (no default). Amgix-One is pre-configured with correct internal value.	Yes	Yes	No
AMGIX_AMQP_URL	RabbitMQ connection URI.	amqp://…, amqps://…	Must be set for API and Encoder (no default). Amgix-One is pre-configured with correct internal value.	Yes	Yes	No
AMGIX_ENCODER_ROLE	Which encoder workloads this encoder process runs.	index, query, all	all	No	Yes	No
AMGIX_LOAD_MODELS	Whether the encoder stack loads Hugging Face / embedding models.	true, false	true	No	Yes	No
AMGIX_LOG_LEVEL	Application log level.	DEBUG, INFO, WARNING, ERROR, CRITICAL	INFO	Yes	Yes	Yes
AMGIX_MEMORY_RESERVE_RAM	RAM headroom reserved for encoder orchestration.	Percent (e.g. 10%) or absolute (e.g. 2G)	10%	No	Yes	Yes
AMGIX_MEMORY_RESERVE_VRAM	GPU VRAM headroom for encoder orchestration.	Percent or absolute	15%	No	Yes	Yes
AMGIX_TRUSTED_ORGS	If true, restrict Hugging Face model loads to “trusted” publishers.	true, false	false	No	Yes	Yes
AMGIX_MODEL_CACHE_SIZE	Max embedding models kept in the encoder LRU cache.	Positive integer	100	No	Yes	Yes
AMGIX_SAFETENSORS	If true, prefer safetensors when loading HF models (dense and sparse).	true, false	false	No	Yes	Yes
HF_TOKEN	Hugging Face token for gated models and rate limits (standard HF env var).	Token string	(unset)	No	Yes	Yes

Notes

AMGIX_ENCODER_ROLE values:

• all: node fully participates in both document processing, search queries and other operations.
• index: node participates in document processing (async, sync, bulk), but does not serve search workloads.
• query: node participates in search queries, but is not involved in processing incoming documents.

AMGIX_LOAD_MODELS values:

• true: node loads embedding models.
• false: models are not allowed on this node.

AMGIX_MEMORY_RESERVE_RAM and AMGIX_MEMORY_RESERVE_VRAM:

• When a node participates in model embedding, these parameters control how much RAM/VRAM it reserves for the rest of system. When the system has less than this amount of free RAM/VRAM, the node will not load any more models.

AMGIX_TRUSTED_ORGS:

• false: Any Hugging Face models will be attempted if requested by collection config.
• true: Enforces a check on model's namespace using predefined list of "trusted organizations". Models from the other namespaces will not be allowed to load. One can override the list by mounting your own list of trusted orgs into Encoder container at /app/src/encoder/trusted_orgs.txt

HF_TOKEN:

• Token is required for accessing gated models. It also allows for increased rate limits from HF. It's not required for operations, but maybe helpful if your Encoders frequently load new (not yet locally cached) models.

Data Persistence

Amgix-One

Amgix-One stores all the data (Qdrant, RabbitMQ and Amgix model caches) in /data. If you would like to persist Amgix data between container restarts, you should mount this directory to host/external storage.

Amgix Encoder

Encoders store model caches in /data. If you would like to persist models between container restarts, you should mount this directory to host/external storage. Otherwise, Encoders will have to download models from HF on first use after every restart.

RabbitMQ and Qdrant/MariaDB/PostgreSQL

If you are running separate instances of RabbitMQ or storage backend (not Amgix-One), and would like to persist your data, follow the normal data persistence practices of the given server.