Skip to main content
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:
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.
Pass a value non-interactively only when shell history and CI logs are protected:
Use polpo byok list and polpo byok remove anthropic to inspect metadata or remove a key.
Provider keys are encrypted with AES-256-GCM. List operations return masked metadata rather than the raw secret.
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.

​
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:
Set the environment variable named by apiKeyEnv before starting the server:
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:
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.