Skip to main content
Tracelane gateway speaks to 205 routable providers through a single API surface. You point at https://gateway.tracelane.dev, set the model string, and we route + failover.

​
Supported providers

Two kinds of adapter sit behind that one surface, and what separates them is the wire format — not how well the provider is supported. Native adapters carry purpose-built request/response translators, because their API shape differs enough from OpenAI’s that a generic adapter would lose fidelity: Bedrock’s SigV4 signing, Anthropic’s messages API, Google’s multi-modal parts. The OpenAI-compatible catalog is every provider that already speaks the OpenAI Chat Completions wire format. It is a data file — crates/gateway/providers.tsv — rather than a match arm per provider, and both tables below are generated from it (plus the adapter fields on ProviderRegistry), so this page cannot claim a provider the gateway does not route. Every value in the Model prefixes column is matched with starts_with. A prefix containing / is tried before a bare one, and bare prefixes are tried longest-first. A model string that matches nothing returns 400 unroutable_model: the router has no default provider, deliberately, so an unrecognised model can never reach some other provider’s key.

​
Native adapters

​
OpenAI-compatible catalog

Each catalog row’s base URL is overridable through the env var in its Base-URL override column, for self-hosted or private-link deployments. The Credential env var column names each native adapter’s primary credential. Three need more than that one value:
  • AWS Bedrock — AWS_SECRET_ACCESS_KEY alongside AWS_ACCESS_KEY_ID, plus AWS_REGION for per-region routing.
  • Azure OpenAI — AZURE_OPENAI_ENDPOINT, and optionally AZURE_OPENAI_API_VERSION (defaults to 2025-01-01-preview).
  • Google Vertex AI — a whole GCP service-account JSON, not an API key.

​
Google: AI Studio vs Vertex AI

Both serve Gemini and take the same model IDs (gemini-2.5-pro, gemini-3-flash-preview, …), but they are different products:
  • gemini-* → AI Studio. Auth is an API key.
  • vertex/* → Vertex AI. Auth is a GCP service-account JSON; Vertex rejects API keys outright. Paste the whole JSON as the credential — we read the project from it. Billed to the linked Cloud project, so Google Cloud credits apply to Vertex but not to AI Studio.
Some models Vertex serves are unavailable to newer AI Studio keys, so vertex/gemini-2.5-flash can work where gemini-2.5-flash returns model_not_found.
Google is retiring classic AIza… API keys. Google now issues AQ.… Authentication Keys from AI Studio, and per Google’s API key docs it stops accepting all Standard (AIza…) keys in September 2026 — unrestricted ones already stopped working in June 2026.If your Google credential starts with AIza, replace it with an AQ. key before September 2026. After the cutoff, calls fail and Tracelane returns provider_key_rejected — not a Tracelane outage.Unaffected: vertex/* (service-account auth), and AIza keys used against non-Gemini Google APIs.

​
Routing

Tracelane routes by model-string prefix:
Model-string aliases go in tracelane.yaml — a models: block mapping an arbitrary name to a provider plus the upstream model to send. Aliases are consulted by exact name, before the prefix table above, so an alias can name one model but never widen the built-in routing.

​
Workspace model aliases

Call a model by a name you control, and change what it points at from Settings → Gateway → Model aliases — no code change, no deploy.
Then send "model": "fast" to /v1/chat/completions or /v1/embeddings.
  • One alias, one target. A target must be a model the gateway can route when you save it, and it cannot be another of your aliases — aliases resolve in one hop. If a target later stops routing, requests for that alias are refused with 400 unroutable_model; the gateway never substitutes a default.
  • Owners only. Only a workspace owner, signed in, can see, add, change or delete aliases. API keys can neither read nor change them.
  • Visible in the trace. The span records the alias you sent as the requested model. When the provider reports which model served the request (OpenAI-compatible providers, Azure OpenAI and Anthropic do), the span records that too and marks the difference as an alias substitution.
  • Applies to your next request. On a deployment running more than one gateway, the other gateways pick up a change within 15 minutes.
  • Up to 50 per workspace.
  • Not applied on the Anthropic-native /v1/messages route.
tracelane.yaml aliases (above) are the operator’s, apply to every workspace on the deployment, and are resolved after yours.

​
Failover

The gateway fails over on upstream 500 / 502 / 503 / 504 (not 429 — a rate-limited upstream returns 429 to the caller with Retry-After). Cross-provider failover is opt-in per request, with the X-Tracelane-Failover: cross-provider header. It is off by default because a silent failover changes which provider saw your prompt, and that is your decision to make, not ours. The chain and the retry policy are operator-configurable in tracelane.yaml:
Every provider id in chain is validated against the provider catalog when the file is read — an unknown id is a startup error naming the line, never a hop that silently does nothing. With no failover: block the built-in chain (Anthropic → OpenAI → Google) applies, which is what every deployment without a config file does today. Retries are same-provider attempts, and the whole sequence is bounded by a fixed wall-clock budget so a retry policy can never multiply a slow upstream. Per-model chains and custom retry_on conditions are still on the roadmap.

​
Upstream error mapping

When an upstream provider rejects a request, the gateway maps it to a distinct status so you can tell whose problem it is. A provider failure is never flattened into a generic “unavailable”. Only the status and a machine-readable reason token cross this boundary — the upstream’s error body never reaches your response or our logs, because provider error bodies can echo the credential that was sent. The key-invalid case covers a shape a status code alone cannot: Google answers a dead API key with 400 API_KEY_INVALID, not 401. Without reading that reason, a retired Google key would look like an outage rather than a credential you need to rotate — which matters most in September 2026 (see the warning above).

​
BYOK provider keys

V1 ships bring-your-own-key only. Provider API keys are envelope- encrypted at rest (AES-256-GCM via ring AEAD, with AAD bound to the tenant + provider) and decrypted in-memory just-in-time on dispatch. They never appear in logs, spans, or error messages. Entitled workspaces can configure a customer KMS wrapped tenant data key for provider-key envelopes through /v1/security/kms.

​
Smoke tests

Each adapter has a wiremock-backed smoke test in crates/gateway/src/providers/smoke_tests.rs. Single-shot, streaming, tool-use, error mapping. Run with:
These use wiremock (loopback mock servers, gated by an RAII SSRF-loopback bypass) and never hit the real network — they catch wire-format drift before it reaches a customer.