Docs / Providers

Providers

A rung is provider/model. Firstpass ships built-in Anthropic and OpenAI providers and lets you add any OpenAI-compatible endpoint with a dialect and auth mode. Bring your own keys; Firstpass adds zero markup.

A rung is provider/model. Firstpass resolves the prefix at call time, calls the vendor API with your own key, and adds zero markup. Anthropic and OpenAI are built in — just set the env var and name the rung. Any other endpoint (Gemini, Bedrock, Vertex, self-hosted) becomes a rung with four config lines — a name, a base URL, a dialect, and an auth mode. Adding a new model is naming a new rung; no classifier to retrain.

The provider model#

Every rung has the form provider/model. The provider prefix is a routing namespace Firstpass resolves at call time to an HTTP endpoint and an auth scheme. The model part is forwarded in the outbound request body. No retraining, no classifier — onboarding a new model is a config line.

Providers are the vendors behind the rungs. When you write anthropic/claude-haiku-4-5 in a ladder, anthropic is the provider and claude-haiku-4-5 is the model. Adding a new model is just naming a new rung — there is no classifier to retrain, which is what makes zero-retrain onboarding possible.

A rung is provider/model. The proxy resolves each rung to its provider and calls it with your own key — Anthropic and OpenAI built in, any OpenAI-compatible host, Gemini, Bedrock (SigV4), Vertex (OAuth), and local runtimes. Adding one is naming a rung; no classifier to retrain.

Key idea The provider prefix is a routing namespace resolved at call time — not at startup, not by a model classifier. Firstpass looks up the provider's base_url, dialect, and auth in config and calls the endpoint directly. That's what makes zero-retrain onboarding possible: a new model is a new string in a ladder, not a training run.

A rung is provider/model; adding a provider is naming a config block, not retraining anything.

Built-in providers#

Anthropic and OpenAI require no [[provider]] block — just set the env var and name the rung. Firstpass reads the key from your environment, forwards it to the provider, and never touches your billing.

Provider	Prefix	Notes
Anthropic	`anthropic/*`	Built in. Live-verified end to end.
OpenAI	`openai/*`	Built in.

Keys come from your environment; Firstpass never proxies through a billing account of its own. BYOK, zero markup — you pay the provider exactly what you would without Firstpass in the path.

Under the hood Keys are read from environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY). Firstpass injects the key into the outbound request's auth header and never logs or stores it. The call goes directly from the proxy to the provider — no intermediate billing account.

BYOK: your key, your provider bill, zero Firstpass markup.

Custom providers#

Any OpenAI-compatible endpoint becomes a rung with four config lines: a name, a base URL, a dialect, and an auth mode. Once declared, reference it as name/model in any ladder — same as a built-in.

Any OpenAI-compatible endpoint becomes a provider with a [[provider]] block — self-hosted models, a gateway, or a cloud-managed endpoint:

The four required fields

toml

[[provider]]
name     = "myllm"
base_url = "https://api.internal.example.com/v1"
dialect  = "openai"        # openai | anthropic | gemini
auth     = "api_key"       # api_key | aws_sigv4 | gcp_oauth

Then use it in a ladder like any other: myllm/mixtral-8x22b.

Common mistake Setting dialect based on the model brand rather than what the endpoint actually speaks. dialect controls how Firstpass serializes the outbound request body — it's an endpoint property, not a model property. A Bedrock endpoint that hosts a Claude model but exposes the Anthropic Messages wire format needs dialect = "anthropic"; an OpenAI-compatible gateway fronting any model needs dialect = "openai". Wrong dialect = serialization mismatch at the provider, not a Firstpass error.

Four fields — name, base_url, dialect, auth — is all it takes to onboard any endpoint as a rung.

Wire dialects#

A dialect is the HTTP wire format a provider endpoint speaks. Outbound: set dialect to match the provider's expected format. Inbound: Firstpass accepts both Anthropic and OpenAI dialects from your client and translates — your client keeps whichever it already uses.

A dialect is the request/response wire format a provider speaks. Firstpass translates so your ladder can mix vendors freely.

Outbound dialects

Dialect	Speaks
`openai`	OpenAI Chat Completions wire format.
`anthropic`	Anthropic Messages wire format.
`gemini`	Gemini wire format.

Inbound dialects

Firstpass also accepts both inbound dialects, so your client keeps whichever it already uses:

POST /v1/messages

Anthropic-style inbound. Live-verified.

POST /v1/chat/completions

OpenAI-style inbound. Live-verified.

Under the hood Firstpass forwards the request body verbatim to same-dialect endpoints, swapping only the model field. Cross-dialect translation — for example, an Anthropic-style inbound request routed to an OpenAI-compatible outbound provider — happens at the proxy layer. The model always receives the format it expects; your client never needs to change.

Set dialect to match the endpoint's wire format; Firstpass handles inbound translation so your client doesn't need to change.

Auth modes#

auth tells Firstpass how to sign the outbound request. api_key covers standard bearer-token endpoints. aws_sigv4 covers Bedrock. gcp_oauth covers Vertex. The mode is a property of the endpoint, not the model.

Custom providers pick an auth mode to match the endpoint — including the cloud-managed model services:

auth	For
`api_key`	Standard bearer-token endpoints.
`aws_sigv4`	AWS SigV4-signed endpoints (e.g. Bedrock).
`gcp_oauth`	GCP OAuth endpoints (e.g. Vertex).

Provider auth extensibility is specified in ADR 0006.

Key idea Auth mode is a property of the endpoint, not the model. Two endpoints serving the same model can require different auth: a direct Anthropic API call uses api_key, the same Claude model accessed via Bedrock requires aws_sigv4. Match the mode to where the request is going, not to what model answers it.

Pick the auth mode that matches the endpoint — Bedrock needs SigV4, Vertex needs GCP OAuth, everything else is api_key.

Verification status#

Anthropic end-to-end and both inbound dialects are live-verified — tested on real traffic against real provider APIs. Other outbound dialects are implemented and exercised by nightly CI, but have not yet been proven on live production traffic.

Firstpass is precise about what has been proven on live wires versus what is implemented and pending verification:

Path	Status
Anthropic, end to end	live-verified
Both inbound dialects	live-verified
Other outbound dialects	awaiting live wire verification

A nightly per-provider smoke CI exercises each dialect so regressions surface before they reach you.

Key idea "Live-verified" means tested on real traffic against the actual provider API, not just unit tests. "Awaiting live wire verification" means the code ships and nightly CI runs the dialect's serialization, but it hasn't been stress-proven on production traffic yet. Anthropic is the proven path today; other dialects gain live-verified status as nightly CI accumulates signal.

Anthropic is the proven path; other dialects are implemented and CI-exercised, gaining live-verified status as signal accumulates.