> ## Documentation Index
> Fetch the complete documentation index at: https://self-hosted-docs.relai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring model provider

> Connect your RELAI deployment to OpenAI, Anthropic, Bedrock, Azure, Foundry, or Vertex AI.

Choose your provider below and add its block to the `.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.

<Tabs sync={false}>
  <Tab title="OpenAI">
    Create a project API key in the [OpenAI Platform](https://platform.openai.com/api-keys), then add:

    ```sh theme={"system"}
    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"
    ```
  </Tab>

  <Tab title="Anthropic">
    Create an API key in the [Anthropic Console](https://console.anthropic.com/settings/keys), then add:

    ```sh theme={"system"}
    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"
    ```

    All three blocks are needed. Without the third, the model proxy that `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.
  </Tab>

  <Tab title="AWS Bedrock">
    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.

    ```sh theme={"system"}
    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"
    ```

    All three blocks are needed. Without the third, the model proxy that `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:

    ```sh theme={"system"}
    RELAI_AGENT_PROVIDER="claude"
    RELAI_AGENT_MODEL_PROVIDER="bedrock"
    RELAI_AGENT_MODEL="<bedrock-claude-model-id>"
    RELAI_AGENT_AWS_REGION="<aws-region>"
    ```

    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.
  </Tab>

  <Tab title="Azure OpenAI">
    Create an Azure OpenAI resource, deploy a model, and copy a key from **Keys and Endpoint**. Use the Azure deployment name in place of `<azure-deployment-name>`.

    ```sh theme={"system"}
    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"
    ```

    If your Azure endpoint requires an API-version query parameter, add this line:

    ```sh theme={"system"}
    RELAI_AGENT_QUERY_PARAMS='{"api-version":"<api-version>"}'
    RELAI_OPTIMIZER_QUERY_PARAMS='{"api-version":"<api-version>"}'
    ```

    Azure provides two resource keys. Rotate by switching to the inactive key, restarting the containers, then regenerating the old key.

    ### 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:

    ```sh theme={"system"}
    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"
    ```

    All three blocks are needed. The first two cover generation and optimization; the third covers the model proxy, which `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 `403` immediately 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 a `401`.
    * The containers can reach the instance metadata service at `169.254.169.254`. If the host routes outbound traffic through an HTTP proxy, add `NO_PROXY="169.254.169.254"` to `.env` so token requests bypass it.

    Every `*_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:

    ```sh theme={"system"}
    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"
    ```

    A response containing `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 run `relai`, 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.

    ```sh theme={"system"}
    # 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"
    ```

    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.

    <Note>
      `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.
    </Note>
  </Tab>

  <Tab title="Azure Foundry Claude">
    Deploy a Claude model in Microsoft Foundry and copy its Project API key. Use the Foundry deployment name for the model value.

    ```sh theme={"system"}
    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"
    ```

    All three blocks are needed. Without the third, the model proxy that `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.
  </Tab>

  <Tab title="Vertex AI Claude">
    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 `.env`:

    ```sh theme={"system"}
    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=""
    ```

    All three blocks are needed. Without the third, the model proxy that `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.

    <Note>
      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.
    </Note>
  </Tab>
</Tabs>

<Tip>
  In case you want to change the provider block in `.env` on a running deployment,
  recreate the affected services to apply the change:

  ```sh theme={"system"}
  docker compose up -d --force-recreate app celery-worker
  ```
</Tip>

## 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.

## Verify the setup

After applying your changes, run a small task in RELAI. If it fails, check that the model or deployment name, endpoint, region, and credential are correct. Container logs identify the provider and model used, but should never contain the key itself.