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

# Model Gateway

> Configure model access, provider keys, and custom gateways

Agent model identifiers use the form `provider/model`, for example `anthropic/claude-sonnet-4-5`. Polpo resolves those identifiers through the configured model gateway or a provider override.

## Managed gateway

Polpo Cloud projects use the managed Vercel AI Gateway by default. No provider key is required for the first deployment.

List the model catalog available to the CLI with:

```bash theme={null}
polpo models list
```

The catalog is the source of truth for current provider and model identifiers; avoid hard-coding a provider count in integrations.

## Bring your own provider key

Provider keys store a project credential for request-scoped use through the managed gateway.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    polpo byok set anthropic
    ```

    Pass a value non-interactively only when shell history and CI logs are protected:

    ```bash theme={null}
    polpo byok set anthropic --key "$ANTHROPIC_API_KEY"
    ```

    Use `polpo byok list` and `polpo byok remove anthropic` to inspect metadata or remove a key.
  </Tab>

  <Tab title="Dashboard">
    Open the project, then go to **Settings > Model Gateway > Provider keys**.
  </Tab>
</Tabs>

Provider keys are encrypted with AES-256-GCM. List operations return masked metadata rather than the raw secret.

<Note>
  Provider keys do not bypass Polpo's gateway and do not inject a plaintext provider key into a sandbox. The gateway receives the decrypted key only for the matching provider request.
</Note>

## Custom gateway

A project can replace the managed gateway with an OpenAI-compatible endpoint and custom headers. Configure it under **Settings > Model Gateway > Custom gateway** when that capability is enabled for the project. Availability depends on the Cloud plan.

The Cloud control plane stores the custom gateway URL and headers in project settings. Store its API key through the gateway BYOK entry instead of putting it in headers or checked-in configuration.

## Runtime configuration

The open-source runtime reads gateway configuration from `.polpo/polpo.json`:

```json theme={null}
{
  "project": "local-project",
  "settings": {
    "gateway": {
      "url": "https://gateway.example.com/v1",
      "apiKeyEnv": "MY_GATEWAY_API_KEY",
      "headers": {
        "HTTP-Referer": "https://example.com"
      }
    }
  }
}
```

Set the environment variable named by `apiKeyEnv` before starting the server:

```bash theme={null}
export MY_GATEWAY_API_KEY=your-key
```

`apiKeyEnv` is an environment variable name, not the secret itself. `settings.gateway.apiKey` and `AI_GATEWAY_URL` are not supported configuration fields.

For the default Vercel AI Gateway, set `AI_GATEWAY_API_KEY`. Provider variables such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY`, and `MISTRAL_API_KEY` are also recognized. The runtime loads `.polpo/.env` as well as process environment variables.

## Custom provider endpoints

Use the top-level `providers` map for a provider-specific OpenAI-compatible endpoint such as Ollama, vLLM, or LM Studio:

```json theme={null}
{
  "project": "local-project",
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions"
    }
  }
}
```

An agent can then use a model such as `ollama/qwen3:8b`. If Polpo runs in Docker and Ollama runs on the host, use a host address reachable from the container, such as `host.docker.internal` where supported.

## Deploying local keys

`polpo deploy` detects recognized provider variables in the process environment and `.polpo/.env`. It prompts before storing them as encrypted Cloud BYOK values. `--yes` and `--force` accept that prompt automatically.