Environment Variables
Getting Started
Most settings can be configured in the AI Optimizer interface, however, you can use environment variables to pre-configure a deployment and enable operational integrations. You can provide them in two ways:
- Create an environment file. This is the preferred approach for reusable local configuration because it keeps related settings together.
- Export values in the shell before starting the application. This is useful for temporary configuration and deployment platforms that inject environment variables.
To create the recommended environment file for local use, copy the example:
cp src/.env.example src/.env.dev
Then edit src/.env.dev and uncomment or add the settings your deployment needs:
AIO_DB_USERNAME=demo
AIO_DB_PASSWORD=replace-with-your-password
AIO_DB_DSN=localhost:1521/FREEPDB1
To export values from the shell for a temporary configuration:
export AIO_DB_USERNAME=demo
export AIO_DB_PASSWORD=replace-with-your-password
export AIO_DB_DSN=localhost:1521/FREEPDB1
A valid CORE database configuration (AIO_DB_USERNAME, AIO_DB_PASSWORD, and AIO_DB_DSN) enables settings persistence and provides the database access required by Vector Search, NL2SQL, and Testbed. Settings configured in the interface are restored from the CORE database after a restart.
Common Starting Configurations
To use a hosted model, configure its provider key. For example:
AIO_OPENAI_API_KEY=replace-with-your-api-key
To use database-backed features, add the CORE database settings shown above. To use a local Ollama model instead of a hosted model provider, set its URL:
AIO_ON_PREM_OLLAMA_URL=http://127.0.0.1:11434
See AI Models for model-provider setup and Oracle AI Database for database connection details.
Environment files can contain API keys, database credentials, wallet passwords, private-key material, and telemetry headers. Do not commit a populated environment file. For shared or hosted deployments, use the platform's secret-management facilities.
How Configuration Works
At startup, the application uses the following precedence:
Environment Files
The entrypoint reads AIO_* variables from the process environment and then loads src/.env.{AIO_ENV} without replacing values already present in the process environment. In a POSIX shell, use export so the application inherits the variables.
Set AIO_ENV before startup to select an environment file. If it is unset, the application uses dev.
AIO_ENV value | File loaded |
|---|---|
dev (default) | src/.env.dev |
prd | src/.env.prd |
| custom | src/.env.{custom} |
Restart the affected component after changing an environment variable.
AIO_* variables are specific to the AI Optimizer. Integrations such as OpenTelemetry and OpenInference use their own variables. See Database Configuration for TNS_ADMIN.
Values supplied through AIO_* variables are reapplied at startup. You can change a matching setting in the interface while the application is running, but the environment value takes effect again after a restart. For the CORE database, DB_* environment variables take precedence over AIO_DB_*; for OCI profiles, OCI_CLI_* variables take precedence over AIO_OCI_CLI_*.
Environment Variables
Application
| Variable | Description | Default |
|---|---|---|
AIO_ENV | Selects the src/.env.{AIO_ENV} file and labels the deployment environment. Set it before startup. | dev |
AIO_LOG_LEVEL | Python logging level | INFO |
Authentication
| Variable | Description | Default |
|---|---|---|
AIO_API_KEY | API key for authenticating requests to the AI Optimizer Server. If unset, a key is generated at startup and displayed on the API Server page. | (generated) |
Client
| Variable | Description | Default |
|---|---|---|
AIO_CLIENT_ADDRESS | Client listen address | localhost |
AIO_CLIENT_PORT | Client listen port | 8501 |
AIO_CLIENT_COOKIE_SECRET | Signing key for the client's XSRF cookies. Multi-replica deployments must provide the same value to every replica. | (none) |
AIO_CLIENT_PASSWORD | Shared password gating configuration and shared-state controls in the GUI client. This does not replace AI Optimizer Server authentication. See Access Control. | (none) |
AIO_CLIENT_SSL | Enables TLS for the Client | false |
AIO_CLIENT_SSL_CERT_FILE | Path to a TLS certificate in PEM format | (none) |
AIO_CLIENT_SSL_KEY_FILE | Path to a TLS private key in PEM format | (none) |
Server
| Variable | Description | Default |
|---|---|---|
AIO_SERVER_URL | URL the client uses to reach the AI Optimizer Server. Set it when the client connects to a separately deployed, remote, or reverse-proxied instance. | (auto-detected) |
AIO_SERVER_URL_PREFIX | URL path prefix for the AI Optimizer Server, such as /optimizer | (none) |
AIO_SERVER_ADDRESS | AI Optimizer Server bind address. A standalone instance uses 0.0.0.0; client autostart uses 127.0.0.1. Clients should connect through AIO_SERVER_URL. | component-specific |
AIO_SERVER_PORT | AI Optimizer Server listen port | 8000 |
AIO_SERVER_SSL | Enables TLS for the AI Optimizer Server | false |
AIO_SERVER_SSL_CERT_FILE | Path to a TLS certificate in PEM format. When TLS is enabled without a certificate, a self-signed certificate is generated. | (none) |
AIO_SERVER_SSL_KEY_FILE | Path to the TLS private key in PEM format | (none) |
AIO_SERVER_READY_TIMEOUT | Seconds the client waits for the AI Optimizer Server to become ready at startup | 180 |
AIO_MAX_CLIENTS | Maximum number of distinct client sessions cached in memory | 64 |
Database
These variables configure the CORE database connection. See Database Configuration for connection formats, wallet setup, and required privileges.
| Variable | Description | Default |
|---|---|---|
AIO_DB_USERNAME | Database username | (none) |
AIO_DB_PASSWORD | Database password | (none) |
AIO_DB_DSN | Connection string or TNS alias | (none) |
AIO_DB_WALLET_PASSWORD | Wallet password for mTLS connections | (none) |
AIO_DB_WALLET_LOCATION | Path to the wallet directory for mTLS connections | (none) |
AIO_DB_POOL_SIZE | Maximum database connection pool size | 5 |
OCI CLI
These settings populate the DEFAULT OCI profile. See OCI Configuration for authentication requirements and supported authentication types.
| Variable | Description | Default |
|---|---|---|
AIO_OCI_CLI_AUTH | Authentication type, such as api_key or instance_principal | (none) |
AIO_OCI_CLI_TENANCY | Tenancy OCID | (none) |
AIO_OCI_CLI_REGION | OCI region | (none) |
AIO_OCI_CLI_USER | User OCID | (none) |
AIO_OCI_CLI_FINGERPRINT | API key fingerprint | (none) |
AIO_OCI_CLI_KEY_FILE | Path to a private key in PEM format | (none) |
AIO_OCI_CLI_KEY_CONTENT | Inline private-key content | (none) |
AIO_OCI_CLI_PASSPHRASE | Private-key passphrase | (none) |
AIO_OCI_CLI_SECURITY_TOKEN_FILE | Path to a security-token file | (none) |
OCI GenAI
| Variable | Description | Default |
|---|---|---|
AIO_GENAI_COMPARTMENT_ID | Compartment OCID for OCI GenAI inference | (none) |
AIO_GENAI_REGION | Region for the OCI GenAI service endpoint | (none) |
OCI Object Storage Source Lock
Pin the Split & Embed tab's OCI source compartment and, optionally, its bucket for every user of the deployment. The compartment must resolve against the active OCI profile. The bucket is only applied when the compartment resolves and the bucket exists in that compartment.
| Variable | Description | Default |
|---|---|---|
AIO_OCI_SOURCE_BUCKET_COMPARTMENT_ID | Compartment OCID pinned as the Split & Embed source compartment. When the OCID resolves, the compartment selector is locked for all users. | (none) |
AIO_OCI_SOURCE_BUCKET_NAME | Bucket pinned within the configured source compartment. If the compartment does not resolve or the bucket does not exist there, this value is ignored. | (none) |
Models
These settings provide API keys or service URLs and enable matching built-in models at startup.
| Variable | Description | Default |
|---|---|---|
AIO_COHERE_API_KEY | Cohere API key | (none) |
AIO_OPENAI_API_KEY | OpenAI API key | (none) |
AIO_PPLX_API_KEY | Perplexity AI API key | (none) |
AIO_ON_PREM_OLLAMA_URL | Ollama API URL, such as http://127.0.0.1:11434 | (none) |
AIO_ON_PREM_HF_URL | Hugging Face TEI URL, such as http://127.0.0.1:8080 | (none) |
AIO_ON_PREM_VLLM_URL | vLLM API URL, such as http://localhost:8000/v1 | (none) |
NL2SQL
| Variable | Description | Default |
|---|---|---|
AIO_SQLCL_HOME | Overrides the SQLcl connection-store directory | (temporary directory) |
AIO_SQLCL_MCP_LEVEL | SQLcl MCP restrict level; integer from 0 to 4 | 4 |
Observability
| Variable | Description | Default |
|---|---|---|
AIO_OTEL_LOGS_ENABLED | Enables application log export after OTLP tracing has been configured. | false |
The AI Optimizer honors the standard OpenTelemetry SDK environment variables. The most relevant ones for operators are listed below.
Endpoint and protocol
| Variable | Description | Default |
|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP receiver URL (all signals) | (unset = OTLP disabled) |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | Trace-specific endpoint (overrides the generic one) | (unset) |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Log-specific endpoint (overrides the generic one) | (unset) |
OTEL_EXPORTER_OTLP_PROTOCOL | grpc or http/protobuf (all signals) | grpc |
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | Trace-specific protocol (overrides the generic one) | (unset) |
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | Log-specific protocol (overrides the generic one) | (unset) |
OTEL_EXPORTER_OTLP_INSECURE | If true, skips TLS for gRPC OTLP. Required for plaintext local SigNoz. | false |
OTEL_EXPORTER_OTLP_HEADERS | Comma-separated k=v headers (for example, vendor authentication) | (unset) |
Exporter selection
| Variable | Description | Default |
|---|---|---|
OTEL_TRACES_EXPORTER | Comma-separated list. Supported values: otlp, console, none. Unsupported values are ignored. | otlp |
OTEL_LOGS_EXPORTER | Comma-separated list. Supported values: otlp, none. Set to none to disable log export when AIO_OTEL_LOGS_ENABLED=true is in effect. | otlp |
Resource attributes
| Variable | Description | Default |
|---|---|---|
OTEL_SERVICE_NAME | Service name shown in the backend | ai-optimizer-server |
OTEL_RESOURCE_ATTRIBUTES | Comma-separated k=v attributes attached to every span (for example, deployment.environment=prd,service.namespace=ai) | (unset) |
Sampling
| Variable | Description | Default |
|---|---|---|
OTEL_TRACES_SAMPLER | Sampler. Common: parentbased_always_on (default), parentbased_traceidratio (probabilistic) | parentbased_always_on |
OTEL_TRACES_SAMPLER_ARG | Sampler argument (for ratio sampler: 0.0–1.0, for example 0.1 for 10%) | (none) |
Batch span processor tuning
The OTEL_BSP_* family (OTEL_BSP_MAX_QUEUE_SIZE, OTEL_BSP_SCHEDULE_DELAY, and others) is honored by the SDK without code changes. Tune it in production if you observe span drops or back-pressure. See the SDK configuration specification for the full list.
OpenInference payload visibility
OpenInference payload fields are hidden by default. Set the relevant OPENINFERENCE_HIDE_* variables to false only for a backend approved to retain prompts, responses, or retrieved content. See Full Payload Export for the supported variables and their effects.
For more information on observability in the AI Optimizer, see the advanced guide.
Containers and Kubernetes
Container
Pass an environment file when starting a container:
podman run --env-file src/.env.dev -p 8501:8501 -it --rm localhost/ai-optimizer-aio:latest
Kubernetes
For Kubernetes, configure the application with Helm values and Kubernetes Secrets. See Kubernetes / Helm and the Helm chart for the available settings.