Runtime configuration reference

alquimia-runtime is configured through environment variables (and an optional .env file). Environment variables always take precedence over values in .env.

Required secrets

The following secrets must be set before the runtime starts. They are never committed to version control.

Secret	Purpose
API_TOKEN	Bearer token for all authenticated endpoints
POSTGRES_USERNAME / POSTGRES_PASSWORD	PostgreSQL credentials
VAULT_TOKEN	Scoped Vault token for registry secret resolution
BLOB_S3_ACCESS_KEY / BLOB_S3_SECRET_KEY	S3-compatible blob storage credentials
KAFKA_SIGNING_KEY	64-character hex key shared across all runtime instances. Used to sign and verify events between masters and workers

Tip

Generate a signing key and encryption key with:

python -c "import secrets; print(secrets.token_hex(32))"

Optionally, set ENCRYPTION_KEY (64-character hex) to enable application-layer AES-256-GCM encryption of Redis conversations and PostgreSQL worklog data at rest. Leave it empty to store data in plaintext.

Service settings

Variable	Required	Default	Description
BACKEND_SERVER_HOST	No	0.0.0.0	Bind address
BACKEND_SERVER_PORT	No	8080	Listen port
BACKEND_SERVER_WORKERS	No	1	Uvicorn worker count
BACKEND_TIMEOUT_KEEP_ALIVE	No	300	Keep-alive timeout (seconds)
DEBUG	No	false	Enable debug mode and verbose logging
RESPONSE_MAX_RETRIES	No	3	Max retries for inference responses
A2A_MAX_DEPTH	No	5	Maximum agent-to-agent call depth
MAX_FILE_CONTENT_SIZE	No	20971520	Max knowledge file upload size in bytes (default 20 MB)
MAX_AUDIO_CONTENT_SIZE	No	6379	Max audio blob size in bytes

Runtime mode

Variable	Required	Default	Description
ALQUIMIA_RUNTIME_MODE	No	master	master serves the external API (registry read/write); worker consumes Kafka events and opens the registry read-only. Use all for single-process local deployments

In production, run master and worker as separate replica sets so they can scale independently. Setting ALQUIMIA_RUNTIME_MODE=worker prevents the local registry from being mutated by inference pods.

Authentication and security

Variable	Required	Default	Description
API_TOKEN	Yes	—	Bearer token for all authenticated endpoints
AUTH_PROVIDER	No	api_token	Auth backend: api_token, jwt, or keycloak
JWT_SECRET	Conditional	""	Required when AUTH_PROVIDER=jwt
JWT_ALGORITHM	No	HS256	JWT signing algorithm
KEYCLOAK_SERVER_URL	Conditional	""	Required when AUTH_PROVIDER=keycloak
KEYCLOAK_REALM	Conditional	""	Keycloak realm
KEYCLOAK_CLIENT_ID	Conditional	""	Keycloak client ID
KEYCLOAK_CLIENT_SECRET	Conditional	""	Keycloak client secret
KEYCLOAK_ADMIN_CLIENT_SECRET	No	""	Falls back to KEYCLOAK_CLIENT_SECRET
KEYCLOAK_CALLBACK_URI	No	""	OAuth callback URI
IS_ALLOWED_CREDENTIALS	No	true	CORS allow credentials
ALLOWED_ORIGINS	No	["*"]	CORS allowed origins. Cannot be ["*"] when IS_ALLOWED_CREDENTIALS=true
ALLOWED_METHODS	No	["*"]	CORS allowed methods
ALLOWED_HEADERS	No	["*"]	CORS allowed headers

See Authentication & authorization for the conceptual model and deployment patterns.

Channel ingress authentication

Channel webhook endpoints (/event/infer/{assistant_id}/{channel_id}) do not use the global bearer token. The runtime delegates authentication to the channel implementation from alquimia-core.

Variable	Required	Default	Description
CHANNEL_AUTH_REQUIRED	No	true	Require every channel to implement provider-specific auth
CHANNEL_MAX_BODY_SIZE	No	1048576	Max channel webhook body size in bytes (default 1 MB)
CHANNEL_RATE_LIMIT_ENABLED	No	true	Enable per-source rate limiting
CHANNEL_RATE_LIMIT_REQUESTS	No	60	Allowed requests per source per window
CHANNEL_RATE_LIMIT_WINDOW_SECONDS	No	60	Rate-limit window

See Channels and Connect a channel for provider-specific setup.

SPIFFE / SPIRE workload identity

Variable	Required	Default	Description
SPIFFE_ENABLED	No	false	Enable SPIFFE workload identity
SPIFFE_SOCKET_PATH	No	/tmp/spire-agent/public/api.sock	Path to the SPIFFE Workload API socket
SPIFFE_TRUST_DOMAIN	No	alquimia.ai	SPIFFE trust domain
AGENTSPACE_PROVISIONING_ENABLED	No	false	Automate SPIRE entries and Vault roles per agentspace
AGENTSPACE_PROVISIONING_INTERVAL_SECONDS	No	300	Reconciliation interval
AGENTSPACE_PROVISIONING_K8S_NAMESPACE	No	spire	Namespace for ClusterStaticEntry CRDs
AGENTSPACE_PROVISIONING_VAULT_JWT_AUTH_PATH	No	jwt	Vault JWT auth mount path

When AGENTSPACE_PROVISIONING_ENABLED=true, the master creates or updates SPIRE ClusterStaticEntry CRDs, scoped Vault ACL policies, and JWT auth roles for each agentspace. A background reconciler runs every AGENTSPACE_PROVISIONING_INTERVAL_SECONDS seconds to converge state with the registry list. This is what produces per-agentspace, per-tier identities that agents use to authenticate to Vault.

See Workload hardening and Authorization policies for the Zero Trust deployment pattern.

Kafka

Variable	Required	Default	Description
KAFKA_BOOTSTRAP_SERVERS	No	localhost:9092	Broker address(es)
KAFKA_TOPIC	No	alquimia.events	Topic for agent events
KAFKA_CONSUMER_GROUP	No	alquimia-workers	Consumer group for workers
KAFKA_SIGNING_KEY	Yes	""	64-character hex signing key shared by all instances
KAFKA_SECURITY_PROTOCOL	No	PLAINTEXT	SASL_SSL or SSL in production
KAFKA_SASL_MECHANISM	No	""	SASL mechanism, e.g. SCRAM-SHA-256
KAFKA_SASL_USERNAME	No	""	SASL username
KAFKA_SASL_PASSWORD	No	""	SASL password
KAFKA_SSL_CA_FILE	No	""	Path to CA certificate for broker verification
KAFKA_SSL_CERT_FILE	No	""	Path to client certificate for mTLS
KAFKA_SSL_KEY_FILE	No	""	Path to client key for mTLS
KAFKA_SSL_VERIFY	No	true	Verify broker certificate hostname
KAFKA_DLQ_TOPIC	No	alquimia.events.dlq	Dead-letter topic for signature-verification failures

Caution

If KAFKA_SIGNING_KEY is not set, all events will fail signature verification and workers will route every message to the DLQ.

External services

Variable	Required	Default	Description
REDIS_URL	No	redis://localhost:6379	Redis connection URL
REDIS_TTL	No	86400	Default TTL for Redis keys (seconds)
POSTGRES_HOST	No	localhost	PostgreSQL host
POSTGRES_PORT	No	5432	PostgreSQL port
POSTGRES_DB	No	alquimia	Database name
POSTGRES_USERNAME	Yes	—	Database user
POSTGRES_PASSWORD	Yes	—	Database password
POSTGRES_SCHEMA	No	postgresql	SQLAlchemy schema prefix
DB_POOL_SIZE	No	60	Connection pool size
DB_MAX_POOL_CON	No	80	Max pool connections
DB_POOL_OVERFLOW	No	20	Pool overflow limit
DB_POOL_PRE_PING	No	true	Pre-ping connections before use
DB_POOL_RECYCLE	No	1800	Connection recycle interval (seconds)
DB_TIMEOUT	No	5	Query timeout (seconds)
DB_CREATE_ON_STARTUP	No	false	Auto-create tables on startup (dev only)
IS_DB_ECHO_LOG	No	false	Log all SQL statements
QDRANT_URL	No	http://localhost:6333	Qdrant vector store URL
QDRANT_API_KEY	No	—	Qdrant API key (optional)
ALQUIMIA_KNOWLEDGE_PROVIDER	No	qdrant	Knowledge-base backend: qdrant, redis, or in_memory. When set, this provider replaces the connector declared on every topic-based, connector-backed knowledge base in the process
VAULT_ADDR	No	vault	HashiCorp Vault address
VAULT_MOUNT_POINT	No	secret	Vault KV mount point
VAULT_TOKEN	Yes	""	Scoped Vault token

Tip

ALQUIMIA_KNOWLEDGE_PROVIDER lets the same agent spec resolve to Qdrant in production, Redis in staging, or in_memory in local tests without editing the spec.

Blob storage (S3 / MinIO)

Variable	Required	Default	Description
BLOB_S3_ENDPOINT_URL	Yes	""	S3-compatible endpoint, e.g. http://minio:9000
BLOB_S3_ACCESS_KEY	Yes	""	S3 access key
BLOB_S3_SECRET_KEY	Yes	""	S3 secret key
BLOB_S3_BUCKET_NAME	Yes	""	Bucket name
BLOB_S3_REGION_NAME	No	us-east-1	S3 region
BLOB_S3_SECURE	No	true	Use TLS for S3 connections

Caution

If any BLOB_S3_* variable is empty, the runtime logs an OBS-003 warning at startup and blob upload/download will fail at runtime.

Registry and OCI

Variable	Required	Default	Description
ALQUIMIA_REGISTRY_DIR	No	—	Local path for TinyDB registry files
ALQUIMIA_OCI_REGISTRY_DEFAULT	No	ghcr.io	Default OCI registry for push/pull
ALQUIMIA_REGISTRY_SECRET_RESOLVER	No	vault	Secret resolver backend: vault or env. env reads directly from environment variables
ALQUIMIA_OCI_SIGNATURE_POLICY	No	required	Signature verification policy: required, warn, or off. required aborts on missing/invalid signatures; warn logs and continues; off skips verification
ALQUIMIA_OCI_COSIGN_KEY	No	—	Path to a cosign public/private key file
ALQUIMIA_OCI_COSIGN_CERT_IDENTITY	No	—	Keyless verification certificate identity
ALQUIMIA_OCI_COSIGN_CERT_OIDC_ISSUER	No	—	Keyless verification OIDC issuer
ALQUIMIA_OCI_DEV_MODE	No	false	Enable insecure ORAS transport flags (dev only)
ORAS_PLAIN_HTTP	No	false	Use plain HTTP for ORAS (gated by ALQUIMIA_OCI_DEV_MODE)
ORAS_INSECURE	No	false	Skip TLS verification for ORAS (gated by ALQUIMIA_OCI_DEV_MODE)

Registry encryption at rest

When ALQUIMIA_REGISTRY_KEY is set, the local TinyDB registry files (metadata.json, <agentspace>/dist.json) are transparently encrypted with AES-256-GCM. The key is a Base64-encoded AES-256 key sourced from Vault or another secret injector.

Variable	Required	Default	Description
ALQUIMIA_REGISTRY_KEY	No	—	Base64-encoded AES-256 key for encryption at rest
ALQUIMIA_REGISTRY_KEY_ID	No	default	Key identifier stored in the ciphertext envelope (rotation support)

Encryption at rest protects against volume or bucket exposure. It does not protect against a compromised runtime process, which can still read decrypted data through the registry APIs. In production, run workers with ALQUIMIA_RUNTIME_MODE=worker so the registry is mounted read-only.

Changing ALQUIMIA_REGISTRY_KEY_ID alongside a new key causes the next write to re-encrypt with the new envelope. If ALQUIMIA_REGISTRY_KEY is absent, the registry falls back to plaintext for backward compatibility.

File storage provider

Registered topic files are stored outside the registry in a pluggable storage backend selected at deployment time.

Variable	Required	Default	Description
ALQUIMIA_FILE_STORAGE_PROVIDER	No	local	Storage backend: local or s3
ALQUIMIA_FILE_STORAGE_LOCAL_DIR	No	$ALQUIMIA_REGISTRY_DIR/files	Local filesystem root for local provider
ALQUIMIA_FILE_STORAGE_S3_ENDPOINT_URL	Conditional	—	Required for s3
ALQUIMIA_FILE_STORAGE_S3_ACCESS_KEY	Conditional	—	Required for s3
ALQUIMIA_FILE_STORAGE_S3_SECRET_KEY	Conditional	—	Required for s3
ALQUIMIA_FILE_STORAGE_S3_BUCKET	Conditional	—	Required for s3
ALQUIMIA_FILE_STORAGE_S3_REGION	No	us-east-1	AWS region for s3

The same provider is used by search_mode="direct" file reads and by alquimia registry topics add-file.

Boltzmann brains

Variable	Required	Default	Description
BRAIN_STORE	No	memory	Where served brains live: memory, or layout:<root>
BRAIN_CACHE_TTL	No	300	Seconds before a cached brain is revalidated
BRAIN_CACHE_MAX_BRAINS	No	4	LRU cache size limit
BRAIN_WARMUP_ENABLED	No	true	Open registered brains at worker startup

Observability

Variable	Required	Default	Description
OTEL_COLLECTOR_ENDPOINT_TRACES	No	—	OTLP HTTP endpoint for traces
OTEL_COLLECTOR_ENDPOINT_LOGS	No	traces endpoint	OTLP HTTP endpoint for logs
OTEL_COLLECTOR_ENDPOINT	No	—	OTLP HTTP endpoint for metrics
OTEL_ALQUIMIA_SERVICE_NAME	No	alquimia	Service name reported to OTEL
OTEL_ALQUIMIA_METER_NAME	No	alquimia-metrics	Meter name for metrics
OTEL_EXPORTER_INTERVAL_MILLIS	No	5000	Metrics export push interval
OTEL_EXCLUDED_ATTRIBUTES	No	""	Comma-separated metric attribute keys to strip before export

See Observability for how the signals correlate.

Related pages

• Deployment configuration
• Docker Compose
• Kubernetes & OpenShift
• Scaling & production