Configuration Reference

alquimia-runtime is configured entirely through environment variables (or a .env file). All settings are loaded by pydantic-settings with strict type coercion and validation at startup.

Precedence: environment variables > .env file > field defaults.

Required variables

These variables have no default and must be set before the service starts.

| Variable | Type | Description | |---|---|---| | API_TOKEN | string | Bearer token for API authentication (used when AUTH_PROVIDER=api_token) | | POSTGRES_USERNAME | string | PostgreSQL username | | POSTGRES_PASSWORD | string | PostgreSQL password |

Runtime mode

| Variable | Default | Description | |---|---|---| | ALQUIMIA_RUNTIME_MODE | master | master — serves the full HTTP API. worker — Kafka consumer only, exposes health probe. |

Server

| Variable | Default | Description | |---|---|---| | BACKEND_SERVER_HOST | 0.0.0.0 | Bind address | | BACKEND_SERVER_PORT | 8080 | Listen port | | BACKEND_SERVER_WORKERS | 1 | Uvicorn worker count | | BACKEND_TIMEOUT_KEEP_ALIVE | 300 | Keep-alive timeout in seconds | | RESPONSE_MAX_RETRIES | 3 | Max retries for a failed ResponseInference call before surfacing an error | | DEBUG | false | Enable debug mode (verbose logging, auto-reload) | | TITLE | Alquimia Runtime Service | Service title (shown in OpenAPI docs) | | VERSION | 0.3.1 | Service version | | TIMEZONE | UTC | Service timezone |

Authentication

| Variable | Default | Description | |---|---|---| | AUTH_PROVIDER | api_token | Authentication backend: api_token, jwt, or keycloak | | API_TOKEN | (required) | Static bearer token (used when AUTH_PROVIDER=api_token) |

Caution

At startup, the service emits a warning if API_TOKEN is set to a known default value ("secret", "test-secret-token", or ""). Always set a strong, unique token in production.

JWT settings

Used when AUTH_PROVIDER=jwt.

| Variable | Default | Description | |---|---|---| | JWT_SECRET | "" | HMAC secret for JWT verification | | JWT_ALGORITHM | HS256 | JWT signing algorithm |

Keycloak settings

Used when AUTH_PROVIDER=keycloak.

| Variable | Default | Description | |---|---|---| | KEYCLOAK_SERVER_URL | "" | Keycloak server URL | | KEYCLOAK_REALM | "" | Keycloak realm name | | KEYCLOAK_CLIENT_ID | "" | Client ID | | KEYCLOAK_CLIENT_SECRET | "" | Client secret | | KEYCLOAK_ADMIN_CLIENT_SECRET | "" | Admin client secret | | KEYCLOAK_CALLBACK_URI | "" | OAuth callback URI |

Database (PostgreSQL)

| Variable | Default | Description | |---|---|---| | POSTGRES_HOST | localhost | PostgreSQL host | | POSTGRES_PORT | 5432 | PostgreSQL port | | POSTGRES_DB | alquimia | Database name | | POSTGRES_USERNAME | (required) | Database username | | POSTGRES_PASSWORD | (required) | Database password | | POSTGRES_SCHEMA | postgresql | SQLAlchemy schema prefix | | DB_MAX_POOL_CON | 80 | Maximum pool connections | | DB_POOL_SIZE | 60 | Connection pool size | | DB_POOL_OVERFLOW | 20 | Pool overflow limit | | DB_POOL_PRE_PING | true | Enable pre-ping health checks | | DB_POOL_RECYCLE | 1800 | Connection recycle interval (seconds) | | DB_TIMEOUT | 5 | Query timeout (seconds) | | DB_CREATE_ON_STARTUP | false | Auto-create tables on startup (dev only — use Alembic in production) | | IS_DB_ECHO_LOG | false | Log all SQL statements | | IS_DB_FORCE_ROLLBACK | false | Force rollback on all transactions (testing only) | | IS_DB_EXPIRE_ON_COMMIT | false | Expire ORM objects on commit |

Run migrations manually:

docker compose exec runtime alembic upgrade head

Redis

| Variable | Default | Description | |---|---|---| | REDIS_URL | redis://localhost:6379 | Redis connection URL | | REDIS_TTL | 86400 | Default key TTL in seconds (24 hours) |

Redis key prefixes

The runtime uses four Redis key namespaces. These are configurable but rarely need to change:

| Variable | Default | Used for | |---|---|---| | CHAT_HISTORY_TOPIC_PREFIX | context- | Conversation message history per session | | BLOB_METADATA_TOPIC_PREFIX | blob- | File attachment metadata per session | | EVENT_STREAM_TOPIC_PREFIX | events- | SSE event queues per task | | CONTROLLER_TOPIC_PREFIX | controller- | Active controller state per task |

Keys are scoped as {prefix}{session_id} or {prefix}{task_id} depending on the namespace. All keys expire after REDIS_TTL seconds.

Kafka

Caution

If KAFKA_SIGNING_KEY is not set at startup, the service emits a warning and all Kafka events will fail signature verification — workers will silently drop every message. Generate with python -c "import secrets; print(secrets.token_hex(32))" and set the same value on the master and all workers.

| Variable | Default | Description | |---|---|---| | KAFKA_BOOTSTRAP_SERVERS | localhost:9092 | Kafka broker address(es) | | KAFKA_TOPIC | alquimia.events | Topic for all agent events | | KAFKA_CONSUMER_GROUP | alquimia-workers | Consumer group shared by all worker replicas | | KAFKA_SIGNING_KEY | (required) | 64-character hex HMAC-SHA256 key — must match across all instances | | KAFKA_SECURITY_PROTOCOL | PLAINTEXT | Set to SASL_SSL in production | | KAFKA_SASL_MECHANISM | "" | SASL mechanism (e.g., SCRAM-SHA-256) | | KAFKA_SASL_USERNAME | "" | SASL username | | KAFKA_SASL_PASSWORD | "" | SASL password |

Vector store (Qdrant)

| Variable | Default | Description | |---|---|---| | QDRANT_URL | http://localhost:6333 | Qdrant server URL | | QDRANT_API_KEY | null | Qdrant API key (optional for self-hosted) |

Blob storage (S3-compatible)

Caution

If any of the S3 settings are empty at startup, the service emits a warning: OBS-003: Blob S3 storage is not fully configured. Context blob upload/download will fail at runtime until these are set.

| Variable | Default | Description | |---|---|---| | BLOB_S3_ENDPOINT_URL | "" | S3 endpoint URL (e.g., http://minio:9000) | | BLOB_S3_ACCESS_KEY | "" | S3 access key | | BLOB_S3_SECRET_KEY | "" | S3 secret key | | BLOB_S3_BUCKET_NAME | "" | S3 bucket name | | BLOB_S3_REGION_NAME | us-east-1 | S3 region | | BLOB_S3_SECURE | true | Use TLS for S3 connections | | MAX_FILE_CONTENT_SIZE | 20971520 | Maximum file upload size in bytes (20 MB) | | MAX_AUDIO_CONTENT_SIZE | 6379 | Maximum audio content size in bytes |

Secrets (Vault)

Caution

If VAULT_TOKEN is empty at startup, the service emits a warning: OBS-002: VAULT_TOKEN is not set. Registry secret resolution via Vault will fail. This is non-fatal — the service starts, but agent inference will fail for any agent using $secretRef values.

| Variable | Default | Description | |---|---|---| | VAULT_ADDR | vault | HashiCorp Vault server address | | VAULT_TOKEN | "" | Vault authentication token | | VAULT_MOUNT_POINT | secret | Vault KV v2 mount point |

The runtime defaults to ALQUIMIA_REGISTRY_SECRET_RESOLVER=vault. Set VAULT_TOKEN to a scoped token — never use the root token in production.

Registry (OCI)

| Variable | Default | Description | |---|---|---| | ALQUIMIA_REGISTRY_DIR | — | Local path for TinyDB registry files. Mounted as a volume in Kubernetes (/var/lib/alquimia/registry). | | ALQUIMIA_OCI_REGISTRY_DEFAULT | ghcr.io | Default OCI registry for push/pull | | ALQUIMIA_REGISTRY_SECRET_RESOLVER | vault | Secret resolver backend: vault or env |

Agent execution

| Variable | Default | Description | |---|---|---| | A2A_MAX_DEPTH | 5 | Maximum agent-to-agent recursion depth |

CORS

Danger

Setting ALLOWED_ORIGINS=["*"] combined with IS_ALLOWED_CREDENTIALS=true raises a RuntimeError at startup and prevents the service from starting. Browsers reject credentialed requests to a wildcard origin. Either set explicit origins or set IS_ALLOWED_CREDENTIALS=false.

| Variable | Default | Description | |---|---|---| | IS_ALLOWED_CREDENTIALS | true | Allow credentials in CORS requests | | ALLOWED_ORIGINS | ["*"] | Allowed CORS origins | | ALLOWED_METHODS | ["*"] | Allowed HTTP methods | | ALLOWED_HEADERS | ["*"] | Allowed HTTP headers |

In production, set explicit origins:

ALLOWED_ORIGINS=["https://app.example.com","https://admin.example.com"]
IS_ALLOWED_CREDENTIALS=true

API paths

| Variable | Default | Description | |---|---|---| | API_PREFIX | /api | API route prefix | | DOCS_URL | /docs | Swagger UI path | | OPENAPI_URL | /openapi.json | OpenAPI schema path | | REDOC_URL | /redoc | ReDoc path |

Logging & observability

Logging

| Variable | Default | Description | |---|---|---| | LOGGING_LEVEL | 20 | Python logging level integer. Common values: 10 (DEBUG), 20 (INFO), 30 (WARNING), 40 (ERROR) |

Runtime OTEL — traces and logs

These variables are read by telemetry.py at startup via os.environ. They are not managed by pydantic-settings — set them as plain environment variables.

Note

The runtime sends traces and logs to separate OTEL endpoints. This allows routing them to different collector pipelines (e.g., Jaeger for traces, Loki for logs). If you use a single collector, set both to the same URL.

| Variable | Default | Description | |---|---|---| | OTEL_COLLECTOR_ENDPOINT_TRACES | — | OTLP HTTP endpoint for traces (e.g., http://otel-collector:4318/v1/traces). Traces are disabled if unset. | | OTEL_COLLECTOR_ENDPOINT_LOGS | (same as traces) | OTLP HTTP endpoint for logs. Defaults to OTEL_COLLECTOR_ENDPOINT_TRACES if unset. | | OTEL_ALQUIMIA_SERVICE_NAME | alquimia | service.name resource attribute attached to all spans and log records |

When OTEL_COLLECTOR_ENDPOINT_TRACES is set, the runtime automatically:

• Creates OTEL spans for every HTTP request via FastAPIInstrumentor
• Tracks CloudEvent spans through the full execution lifecycle via finalize_span middleware
• Bridges all loguru log records to OTEL logs with span context and CommonAttributes dimensions attached

Core SDK OTEL — metrics

These variables are read by alquimia-core’s observability.py at import time. They control the metrics pipeline, which is separate from the runtime’s traces/logs pipeline.

Note

Metrics are emitted by alquimia-core (the SDK), not by the runtime service itself. Call setup_observability() once at application startup to enable them. See Core SDK Observability for the full metrics reference.

| Variable | Default | Description | |---|---|---| | OTEL_COLLECTOR_ENDPOINT | — | OTLP HTTP endpoint for metrics (e.g., http://otel-collector:4318/v1/metrics). Metrics are disabled if unset. | | OTEL_EXPORTER_INTERVAL_MILLIS | 5000 | How often metrics are exported to the collector, in milliseconds | | OTEL_ALQUIMIA_METER_NAME | alquimia-metrics | Meter name used to identify the metrics source in the collector | | OTEL_ALQUIMIA_SERVICE_NAME | alquimia | service.name resource attribute (shared with runtime OTEL if both are set) | | OTEL_EXCLUDED_ATTRIBUTES | "" | Comma-separated list of metric dimension keys to strip before export (e.g., user_id,session_id for privacy) |

Full observability setup example

.env (production with OTEL)

# Runtime: traces and logs
OTEL_COLLECTOR_ENDPOINT_TRACES=http://otel-collector:4318/v1/traces
OTEL_COLLECTOR_ENDPOINT_LOGS=http://otel-collector:4318/v1/logs
OTEL_ALQUIMIA_SERVICE_NAME=alquimia-runtime

# Core SDK: metrics (set in the same environment)
OTEL_COLLECTOR_ENDPOINT=http://otel-collector:4318/v1/metrics
OTEL_EXPORTER_INTERVAL_MILLIS=10000
OTEL_ALQUIMIA_METER_NAME=alquimia-metrics

Startup warnings

The service emits non-fatal warnings at startup for common misconfigurations. These appear in logs as [STARTUP CONFIG] entries:

| Warning code | Condition | Impact | |---|---|---| | OBS-002 | VAULT_TOKEN is empty | Agent inference fails for any agent using $secretRef | | OBS-002 | API_TOKEN is a default/test value | Security risk in production | | OBS-003 | Any S3 blob setting is empty | Context blob upload/download fails at runtime |

These warnings are intentionally non-fatal — the service starts regardless. The goal is to surface misconfiguration early in logs rather than at first request time.

Minimal .env for local development

.env

# Required
API_TOKEN=dev-token
POSTGRES_USERNAME=alquimia
POSTGRES_PASSWORD=alquimia

# Services
REDIS_URL=redis://localhost:6379
QDRANT_URL=http://localhost:6333
BLOB_S3_ENDPOINT_URL=http://localhost:9000
BLOB_S3_ACCESS_KEY=minioadmin
BLOB_S3_SECRET_KEY=minioadmin
BLOB_S3_BUCKET_NAME=alquimia

# Auth (dev mode — use env resolver, not Vault)
AUTH_PROVIDER=api_token
ALQUIMIA_REGISTRY_SECRET_RESOLVER=env

# CORS (dev mode — set explicit origins in production)
ALLOWED_ORIGINS=["http://localhost:3000"]
IS_ALLOWED_CREDENTIALS=true

# Secrets (resolved from env when using env resolver)
OPENAI_API_KEY=sk-...

Related pages

• Observability — the full observability model
• Core SDK Observability — metrics reference
• Runtime Observability — traces, logs, and middleware
• Docker Compose — full stack setup
• Inference Endpoints — API reference
• Registry API — registry management

Source

• Alquimia-ai/alquimia-runtime — runtime/src/config.py (all settings), runtime/src/telemetry.py (OTEL setup), docker-compose.yml, .env.example
• Alquimia-ai/alquimia-core — src/alquimia/core/observability.py (metrics setup)