environment.md

Environment variables

!!! note "Generated page" scripts/docs/gen_env.py builds this page from the code. Text that needs a person lives in scripts/docs/descriptions.yml. Edit that file, not this page.

common/settings.py loads a .env file with dotenv.load_dotenv() when it is imported, so values in .env count as environment variables. Every read below sits under api/, common/ or conserver/. Tests are left out.

A default of none means the read returns nothing when the variable is unset. required means the code raises KeyError when it is unset. A variable set to an empty value counts as set, so its default does not apply.

Each process reads these values when it starts, so restart it after a change. For help choosing values, see the environment guide.

The code reads 40 variables.

Variable	Default	Type	Read in	Description
API_ROOT_PATH	/api	string	common/settings.py	FastAPI root_path for the API app, for a proxy that strips this prefix. Route paths do not change.
CONSERVER_API_TOKEN	none	string	common/settings.py	One API key for the main API routes. With neither this nor CONSERVER_API_TOKEN_FILE set, the API skips authentication on those routes.
CONSERVER_API_TOKEN_FILE	none	string	common/settings.py	Path to a file of API keys, one per line, read once when the API starts. Added to the keys from CONSERVER_API_TOKEN.
CONSERVER_CONFIG_FILE	./example_config.yml in common/settings.py none in api/api.py	string	api/api.py common/settings.py	Path to the YAML configuration. common/config.py reads it through the setting and its default. The POST /config handler reads the variable directly, with no default, to write the file. An empty value fails when the file is opened.
CONSERVER_HEADER_NAME	x-conserver-api-token	string	common/settings.py	HTTP header that carries the API key. The follower also sends its auth token in this header.
CONSERVER_PARALLEL_STORAGE	true	boolean	common/settings.py	When true, and a chain has more than one storage backend, writes run in parallel. true, 1 and yes count as true, in any case.
CONSERVER_START_METHOD	""	string	common/settings.py	Multiprocessing start method, one of fork, spawn or forkserver. Used only when CONSERVER_WORKERS is above 1. Empty or unset uses the Python platform default. Any other value raises ValueError at startup.
CONSERVER_VCON_CONCURRENCY	1	integer	common/settings.py	In-flight vCons per worker process. Values under 1 become 1, which processes vCons serially.
CONSERVER_WORKERS	1	integer	common/settings.py	Number of worker processes. Values under 1 become 1.
DEEPGRAM_KEY	none	string	common/settings.py	Read into settings, but no code uses that setting. The deepgram_link link takes its key from link options.
EGRESS_FORMAT_VERSION	none	string	common/settings.py	Legacy vCon version string emitted by the webhook link, the postgres, s3 and elasticsearch storage adapters and the GET /vcon/{uuid} and GET /vcons reads. 0.0.1 is the only supported value. Empty or unset emits the current spec. Redis and link processing stay on the current spec either way.
ENV	dev in common/settings.py required in common/lib/error_tracking.py	string	common/lib/error_tracking.py common/settings.py	Sentry environment name. The settings value is unused. common/lib/error_tracking.py reads the variable directly when SENTRY_DSN is set, and has no default.
GROQ_API_KEY	YOUR_GROQ_API_KEY	string	conserver/links/groq_whisper/__init__.py	Default API_KEY option for the groq_whisper link.
HOSTNAME	http://localhost:8000	string	common/settings.py	Read into settings, but no code uses that setting.
LOGGING_CONFIG_FILE	logging.conf beside common/settings.py	string	common/settings.py	Path passed to logging.config.fileConfig. The repo also ships common/logging_dev.conf.
LOG_LEVEL	DEBUG	string	common/settings.py	Read into settings, but no code uses that setting. The logging config file sets log levels.
OPENAI_API_KEY	"" in conserver/links/detect_engagement/__init__.py none in common/settings.py	string	common/settings.py conserver/links/detect_engagement/__init__.py	Default OPENAI_API_KEY option for the detect_engagement link. The settings value is unused. Other links take the key from link options.
OTEL_EXPORTER_OTLP_ENDPOINT	none	string	common/lib/metrics.py	OTLP endpoint for metrics, passed to the gRPC exporter in common/lib/metrics.py. Unset or empty, the metric helpers do nothing.
OTEL_METRIC_EXPORT_INTERVAL	5000	integer	common/lib/metrics.py	Metric export interval in milliseconds.
OTEL_SERVICE_NAME	vcon-server	string	common/lib/metrics.py	Value of the service.name resource attribute on metrics. The Compose file sets conserver and api.
REDIS_URL	redis://localhost	string	common/settings.py	Redis connection URL. docker/wait_for_redis.sh reads it too, and skips its wait when it is unset or empty.
SENTRY_DSN	none	string	common/lib/error_tracking.py	Sentry DSN. Unset, Sentry stays off. Set, ENV must be in the process environment too.
SXT_API_KEY	none	string	common/storage/spaceandtime/__init__.py	Space and Time API key for the spaceandtime storage adapter.
SXT_VCON_TABLENAME	none	string	common/storage/spaceandtime/__init__.py	Table name for the spaceandtime storage adapter.
SXT_VCON_TABLE_WRITE_BISCUI	none	string	common/storage/spaceandtime/__init__.py	Write biscuit for the spaceandtime storage adapter. The code reads this exact name, which lacks the final T of the Python constant SXT_VCON_TABLE_WRITE_BISCUIT.
TICK_INTERVAL	5000	integer	common/settings.py	Read into settings, but no code uses that setting.
UUID8_DOMAIN_NAME	a domain set in code	string	common/vcon.py	Read into a constant in common/vcon.py, but no code uses that constant.
VCON_CONTEXT_EXPIRY	86400	integer	common/settings.py	Seconds before ingress context data expires in Redis.
VCON_DLQ_EXPIRY	604800	integer	common/settings.py	TTL in seconds for a vCon in a dead letter queue. The ingress DLQ sets the TTL to this value. The storage DLQ only raises a lower TTL. 0 leaves the existing TTL alone.
VCON_INDEX_EXPIRY	86400	integer	common/settings.py	Seconds before the search index keys written by the API expire.
VCON_REDIS_EXPIRY	3600	integer	common/settings.py	TTL in seconds on vCon keys written by POST /vcon and POST /vcon/external-ingress, and on a vCon cached back from a storage backend.
VCON_SERVER_BUILD_TIME	unknown	string	common/version.py	Image build time. The Dockerfiles set it from a build argument.
VCON_SERVER_GIT_COMMIT	unknown in common/version.py none in common/lib/error_tracking.py	string	common/lib/error_tracking.py common/version.py	Git commit of the build. The Dockerfiles set it from a build argument. Sentry uses it as the release.
VCON_SERVER_VERSION	dev	string	common/version.py	Server version string. The Dockerfiles set it from a build argument.
VCON_SORTED_FORCE_RESET	true	string	common/settings.py	Read into settings, but no code uses that setting.
VCON_SORTED_SET_NAME	vcons	string	common/settings.py	Name of the Redis sorted set that orders vCons by timestamp.
VCON_STORAGE	""	string	common/settings.py	PostgreSQL connection string. When set, api/api.py defines a Peewee model on it, but no code uses that model.
VCON_STORAGE_FALLBACK_ENABLED	true	boolean	common/settings.py	When true, a Redis miss in VconRedis.get_vcon tries the configured storage backends and caches the first hit back in Redis. true, 1 and yes count as true, in any case.
WEVIATE_API_KEY	none	string	common/settings.py	Read into settings, but no code uses that setting. The spelling is the one in the code.
WEVIATE_HOST	localhost:8000	string	common/settings.py	Read into settings, but no code uses that setting. The spelling is the one in the code.

Dynamic reads

These reads compute the variable name at run time, so the table cannot list them.

File	Expression
conserver/links/groq_whisper/__init__.py	var in os.environ

The dynamic read in groq_whisper does not configure anything. When that link module loads, it deletes HTTP_PROXY, HTTPS_PROXY, NO_PROXY and their lowercase forms from the process environment.

Variables outside the server code

Scripts, Docker Compose and the OpenTelemetry tools read these. The table above leaves them out because no code under api/, common/ or conserver/ reads them.

Variable	Read by	Default	Description
COMPOSE_PROFILES	Docker Compose	none	Comma-separated profiles to start: postgres, elasticsearch, langfuse.
CONSERVER_EXTERNAL_PORT	docker-compose.yml	8000	Host port published for the api service.
OTEL_EXPORTER_OTLP_HEADERS	opentelemetry-instrument	empty	Headers for OTLP export. Compose passes it to api and conserver.
OTEL_EXPORTER_OTLP_INSECURE	opentelemetry-instrument	false in Compose	Turns off TLS for OTLP export. Compose passes it to api and conserver.
OTEL_EXPORTER_OTLP_PROTOCOL	opentelemetry-instrument	grpc in Compose	OTLP protocol. The custom metrics in common/lib/metrics.py always use the gRPC exporter, whatever this says.
OTEL_RESOURCE_ATTRIBUTES	opentelemetry-instrument	deployment.environment=dev in Compose	Resource attributes. The Compose file fixes this value for api and conserver.
REDIS_MIGRATION_SOURCE_URL	scripts/migrate_redis_json.py	required	Redis URL to copy from. See the Redis migration.
REDIS_MIGRATION_TARGET_URL	scripts/migrate_redis_json.py	required	Redis URL to copy to.