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 Model Gateway > Custom gateway. On Polpo Cloud, this requires the organization’s custom_gateway entitlement, included in Startup. Free, Pro, and Pay as you go do not include it. The Cloud API checks this entitlement when saving the gateway URL or key and when resolving the gateway for execution. Missing access returns 402 custom_gateway_not_enabled; an unavailable entitlement check returns 503 billing_unavailable. Existing configuration does not bypass the check. Removing the gateway to return to managed model access remains available without the entitlement. These Cloud plan restrictions do not apply to the open-source runtime. 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.

​
Structured output

For Chat Completions response_format: { "type": "json_schema", ... } and Loop Agent steps with output.schema, Polpo sends the schema to the custom gateway as json_schema with strict: true. The gateway and selected model must support and forward structured output. Polpo validates the response locally as well and does not silently downgrade a schema request to json_object. Use a schema compatible with the target provider. For OpenAI strict output, every object must set additionalProperties: false and list all properties in required. An optional value can use a nullable type; an array can be required and empty when its contract permits it. Polpo does not automatically rewrite optional fields or change their meaning. Plain text and explicit json_object requests are unaffected.

​
Runtime configuration

The open-source runtime reads gateway configuration from .polpo/project.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.