.env file beside your Docker Compose file before you start the platform.
Keep both the RELAI_AGENT_* and RELAI_OPTIMIZER_* settings from the chosen block. They configure the different parts of RELAI that make model requests. Only edit the values in angle brackets — replace each <...> placeholder with your own value before starting the containers. Every other value is a fixed constant; leave it exactly as shown.
- OpenAI
- Anthropic
- AWS Bedrock
- Azure OpenAI
- Azure Foundry Claude
- Vertex AI Claude
Create a project API key in the OpenAI Platform, then add:
OPENAI_API_KEY="<openai-api-key>"
RELAI_AGENT_PROVIDER="codex"
RELAI_AGENT_MODEL_PROVIDER="openai"
RELAI_AGENT_MODEL="<openai-model-id>"
RELAI_AGENT_API_KEY_ENV="OPENAI_API_KEY"
RELAI_OPTIMIZER_PROVIDER="openai"
RELAI_OPTIMIZER_MODEL="<openai-model-id>"
RELAI_OPTIMIZER_API_KEY_ENV="OPENAI_API_KEY"
RELAI_OPTIMIZER_WIRE_API="responses"
Create an API key in the Anthropic Console, then add:All three blocks are needed. Without the third, the model proxy that
ANTHROPIC_API_KEY="<anthropic-api-key>"
RELAI_AGENT_PROVIDER="claude"
RELAI_AGENT_MODEL_PROVIDER="anthropic"
RELAI_AGENT_MODEL="<claude-model-id>"
RELAI_CLAUDE_API_KEY_ENV="ANTHROPIC_API_KEY"
RELAI_OPTIMIZER_PROVIDER="anthropic"
RELAI_OPTIMIZER_MODEL="<claude-model-id>"
RELAI_OPTIMIZER_API_KEY_ENV="ANTHROPIC_API_KEY"
RELAI_OPTIMIZER_WIRE_API="chat_completions"
RELAI_MODEL_PROXY_MODEL="anthropic/<claude-model-id>"
RELAI_MODEL_PROXY_API_KEY_ENV="ANTHROPIC_API_KEY"
relai init uses keeps its default of gpt-5.4 on OpenAI, so RELAI would still call OpenAI even though generation and optimization run on Anthropic.In the Amazon Bedrock console, create a long-term API key, restrict it to the models you will use, and set an expiration. Also enable access to each model in Bedrock before testing.All three blocks are needed. Without the third, the model proxy that AWS recommends short-lived credentials for production. If you use a long-term key, use the shortest practical expiration and rotate it before it expires.
AWS_BEARER_TOKEN_BEDROCK="<aws-bedrock-api-key>"
AWS_REGION="<aws-region>"
# For an OpenAI model on Bedrock
RELAI_AGENT_PROVIDER="codex"
RELAI_AGENT_MODEL_PROVIDER="amazon-bedrock"
RELAI_AGENT_MODEL="<bedrock-openai-model-id>"
RELAI_AGENT_AWS_REGION="<aws-region>"
# Use either an OpenAI or Claude Bedrock model here
RELAI_OPTIMIZER_PROVIDER="aws-bedrock"
RELAI_OPTIMIZER_MODEL="<bedrock-model-id>"
RELAI_OPTIMIZER_API_KEY_ENV="AWS_BEARER_TOKEN_BEDROCK"
RELAI_OPTIMIZER_WIRE_API="chat_completions"
RELAI_MODEL_PROXY_MODEL="bedrock/<bedrock-model-id>"
RELAI_MODEL_PROXY_API_KEY_ENV="AWS_BEARER_TOKEN_BEDROCK"
relai init uses keeps its default of gpt-5.4 on OpenAI, so RELAI would still call OpenAI even though generation and optimization run on Bedrock.To use Claude for the first model setting instead, replace the four RELAI_AGENT_* lines above with:RELAI_AGENT_PROVIDER="claude"
RELAI_AGENT_MODEL_PROVIDER="bedrock"
RELAI_AGENT_MODEL="<bedrock-claude-model-id>"
RELAI_AGENT_AWS_REGION="<aws-region>"
Create an Azure OpenAI resource, deploy a model, and copy a key from Keys and Endpoint. Use the Azure deployment name in place of If your Azure endpoint requires an API-version query parameter, add this line:Azure provides two resource keys. Rotate by switching to the inactive key, restarting the containers, then regenerating the old key.All three blocks are needed. The first two cover generation and optimization; the third covers the model proxy, which A response containing Your own agent’s credentials are separate from all of the above. If your agent selects a model implicitly, whatever name its framework picks must also exist as a deployment — pinning the model in your agent avoids that surprise.
<azure-deployment-name>.AZURE_OPENAI_API_KEY="<azure-openai-api-key>"
RELAI_AGENT_PROVIDER="codex"
RELAI_AGENT_MODEL_PROVIDER="azure"
RELAI_AGENT_MODEL="<azure-deployment-name>"
RELAI_AGENT_BASE_URL="https://<azure-resource-name>.openai.azure.com/openai/v1"
RELAI_AGENT_API_KEY_ENV="AZURE_OPENAI_API_KEY"
RELAI_OPTIMIZER_PROVIDER="azure-openai"
RELAI_OPTIMIZER_MODEL="<azure-deployment-name>"
RELAI_OPTIMIZER_BASE_URL="https://<azure-resource-name>.openai.azure.com/openai/v1"
RELAI_OPTIMIZER_API_KEY_ENV="AZURE_OPENAI_API_KEY"
RELAI_OPTIMIZER_WIRE_API="responses"
RELAI_AGENT_QUERY_PARAMS='{"api-version":"<api-version>"}'
RELAI_OPTIMIZER_QUERY_PARAMS='{"api-version":"<api-version>"}'
Managed identity
If your resource authenticates with Microsoft Entra ID rather than a key, leave the key variable out entirely and name a credential instead:RELAI_AGENT_PROVIDER="codex"
RELAI_AGENT_MODEL_PROVIDER="azure"
RELAI_AGENT_MODEL="<azure-deployment-name>"
RELAI_AGENT_BASE_URL="https://<azure-resource-name>.openai.azure.com/openai/v1"
RELAI_AGENT_AZURE_CREDENTIAL="managed-identity"
RELAI_OPTIMIZER_PROVIDER="azure-openai"
RELAI_OPTIMIZER_MODEL="<azure-deployment-name>"
RELAI_OPTIMIZER_BASE_URL="https://<azure-resource-name>.openai.azure.com/openai/v1"
RELAI_OPTIMIZER_AZURE_CREDENTIAL="managed-identity"
RELAI_OPTIMIZER_WIRE_API="responses"
RELAI_MODEL_PROXY_MODEL="<azure-deployment-name>"
RELAI_MODEL_PROXY_BASE_URL="https://<azure-resource-name>.openai.azure.com/openai/v1"
RELAI_MODEL_PROXY_AZURE_CREDENTIAL="managed-identity"
relai init uses. Without it, relai init stops with “The model proxy is not configured”.RELAI requests a short-lived token for each model call, so there is no key to store or rotate. For a user-assigned identity, also set AZURE_CLIENT_ID to its client ID, since a host can carry more than one. Set RELAI_AZURE_TOKEN_SCOPE only for a sovereign cloud whose token audience differs from the public one.Three things have to be true on the Azure side:- The host’s identity holds the Cognitive Services OpenAI User role on the Azure OpenAI resource. A new role assignment can take up to five minutes to take effect, so a
403immediately after granting it is expected. - The resource has a custom subdomain, as in
https://<azure-resource-name>.openai.azure.com. A regional endpoint rejects Entra ID tokens with a401. - The containers can reach the instance metadata service at
169.254.169.254. If the host routes outbound traffic through an HTTP proxy, addNO_PROXY="169.254.169.254"to.envso token requests bypass it.
*_MODEL value is an Azure deployment name, not a model name. Sending a model name that has no deployment returns DeploymentNotFound.To confirm the identity works before starting the platform:docker compose exec celery-worker curl -s -H "Metadata: true" \
"http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fai.azure.com"
access_token means the identity and the role assignment are both in place. Append &client_id=<client-id> when using a user-assigned identity.Running the RELAI CLI
Learning environments score their results on the machine where you runrelai, not inside the containers, so that machine needs two things of its own. On an Azure host its managed identity supplies the credential; on a workstation an az login session does.# once, in the simulator environment the CLI creates
.relai/simulator/.venv/bin/pip install azure-identity
# in the shell that runs relai — note this one has no /openai/v1 suffix
export RELAI_MODEL_PROVIDER_LITELLM_BASE_URL="https://<azure-resource-name>.openai.azure.com"
managed-identity expects an Azure-hosted identity. default instead walks the standard Azure credential chain, which also picks up an az login session — useful when trying the configuration from a workstation. Both require RELAI_BACKEND_SERVICE_VERSION 1.30.4 or later.Deploy a Claude model in Microsoft Foundry and copy its Project API key. Use the Foundry deployment name for the model value.All three blocks are needed. Without the third, the model proxy that
AZURE_FOUNDRY_API_KEY="<azure-foundry-api-key>"
RELAI_AGENT_PROVIDER="claude"
RELAI_AGENT_MODEL_PROVIDER="foundry"
RELAI_AGENT_MODEL="<foundry-claude-deployment-name>"
RELAI_AGENT_FOUNDRY_RESOURCE="<foundry-resource-name>"
RELAI_CLAUDE_API_KEY_ENV="AZURE_FOUNDRY_API_KEY"
RELAI_OPTIMIZER_PROVIDER="azure-foundry"
RELAI_OPTIMIZER_MODEL="<foundry-claude-deployment-name>"
RELAI_OPTIMIZER_BASE_URL="https://<foundry-resource-name>.services.ai.azure.com/anthropic"
RELAI_OPTIMIZER_API_KEY_ENV="AZURE_FOUNDRY_API_KEY"
RELAI_OPTIMIZER_WIRE_API="chat_completions"
RELAI_MODEL_PROXY_MODEL="anthropic/<foundry-claude-deployment-name>"
RELAI_MODEL_PROXY_BASE_URL="https://<foundry-resource-name>.services.ai.azure.com/anthropic"
RELAI_MODEL_PROXY_API_KEY_ENV="AZURE_FOUNDRY_API_KEY"
relai init uses keeps its default of gpt-5.4 on OpenAI, so RELAI would still call OpenAI even though generation and optimization run on Foundry.Vertex AI requires a Google service-account key file rather than a portable API key. Create a dedicated service account with Vertex AI and Claude model access, create a JSON key, and keep it outside the Docker image.Add the following to All three blocks are needed. Without the third, the model proxy that
.env:GCP_VERTEX_KEY_PATH="<host-path-to-key>"
GOOGLE_APPLICATION_CREDENTIALS="/run/secrets/gcp-vertex.json"
VERTEXAI_PROJECT="<gcp-project-id>"
VERTEXAI_LOCATION="<vertex-location>"
RELAI_AGENT_PROVIDER="claude"
RELAI_AGENT_MODEL_PROVIDER="vertex"
RELAI_AGENT_MODEL="<vertex-claude-model-id>"
RELAI_AGENT_VERTEX_PROJECT_ID="<gcp-project-id>"
RELAI_AGENT_VERTEX_REGION="<vertex-location>"
RELAI_OPTIMIZER_PROVIDER="vertex-ai"
RELAI_OPTIMIZER_MODEL="<vertex-claude-model-id>"
RELAI_OPTIMIZER_WIRE_API="chat_completions"
RELAI_MODEL_PROXY_MODEL="vertex_ai/<vertex-claude-model-id>"
RELAI_MODEL_PROXY_API_KEY_ENV=""
relai init uses keeps its default of gpt-5.4 on OpenAI, so RELAI would still call OpenAI even though generation and optimization run on Vertex AI.Leave RELAI_MODEL_PROXY_API_KEY_ENV empty: Vertex AI authenticates with the mounted service-account key rather than an API key, so naming a key variable here would send the wrong credential.docker-compose.yml already mounts GCP_VERTEX_KEY_PATH read-only into the app and celery-worker containers at /run/secrets/gcp-vertex.json — no compose file edits needed.Vertex AI support in the model proxy requires backend version 1.44.2 or later. On earlier versions,
RELAI_MODEL_PROXY_MODEL="vertex_ai/..." fails with vertexai import failed; leave the proxy variables out and it stays on its OpenAI default.In case you want to change the provider block in
.env on a running deployment,
recreate the affected services to apply the change:docker compose up -d --force-recreate app celery-worker
Use Django Admin instead
You can configure the same values in Django Admin under Agent Studio. Add and enable a Generation Runtime Config and an Optimizer Runtime Config, using the provider and model values from the matching block above. An enabled Admin entry takes precedence over.env for that setting.