Repository navigation
Releases
Releases · raven-clown/transponder
v0.3.0
What's Changed
Changed
- Breaking:
${VAR}in the config file fills in part of one value and can no longer add YAML structure. A variable that held a list or a map, such astargets: ${TARGETS}, is now read as a string and the file is refused. Move such lists into the file and keep only secrets in variables (#136). by @raven-clown in #160
Added
--config-testflag to validate a configuration file, environment variables, provider routes and settings without starting the server, binding listening ports, or creating a database file (#103). by @nikhil-mewar in #113- Every response carries
X-Request-ID: the caller's value when it is 1 to 128 printable ASCII characters, or a new 32-character hex id. The same id is recorded with usage and sent to the provider. by @brevitywithorion in #114 - Every line the JSON logger writes carries
"service":"transponder", so logs from the four projects can be told apart in one place. by @brevitywithorion in #115 - Mistral AI provider (
type: mistral) defaulting tohttps://api.mistral.ai/v1and sendingapi_keyas a bearer token. Chat and embeddings (mistral-embed) share that base URL. Abase_urlstill overrides that default. No prices are included, so calls are logged as unpriced. by @brevitywithorion in #109 - NVIDIA NIM provider (
type: nvidia) defaulting tohttps://integrate.api.nvidia.com/v1and sendingapi_keyas a bearer token. Abase_urlstill overrides that default. A self-hosted NIM is usuallyhttp://localhost:8000/v1. No prices are included, so calls are logged as unpriced. by @brevitywithorion in #116 - Groq provider (
type: groq) defaulting tohttps://api.groq.com/openai/v1and sendingapi_keyas a bearer token. Abase_urlstill overrides that default. No prices are included, so calls are logged as unpriced. by @brevitywithorion in #108 - Cerebras provider (
type: cerebras) defaulting tohttps://api.cerebras.ai/v1and sendingapi_keyas a bearer token. Abase_urlstill overrides that default. No prices are included, so calls are logged as unpriced. by @brevitywithorion in #110 - SiliconFlow provider (
type: siliconflow) defaulting tohttps://api.siliconflow.com/v1and sendingapi_keyas a bearer token. Abase_urlstill overrides that default. The China host ishttps://api.siliconflow.cn/v1. No prices are included, so calls are logged as unpriced. by @brevitywithorion in #117 - LM Studio provider (
type: lmstudio) defaulting tohttp://localhost:1234/v1.api_keyis optional and, when set, is sent as a bearer token. Targets usinglmstudiocount as free in usage costs. by @brevitywithorion in #118 store.postgres(orTRANSPONDER_STORE__POSTGRES) keeps API keys and usage records in Postgres, so several replicas can share them. The schema is migrated at start, and replicas that start together apply each migration once. by @raven-clown in #160- Every replica checks the
config_versionrow in the store every 2 seconds and, when it changed, loads and validates the whole runtime config and swaps it in. A config that fails to load leaves the old one serving and is logged once. Calls already running finish on the config they started with. The admin API will raise the version with each write. by @raven-clown in #160 - With
store.postgres, budgets, token allowances, request rates and concurrency caps are counted in Postgres, so they hold across every replica. Two replicas cannot both spend the last of a budget.limits.store: memorykeeps per-process counters for a single replica. When Postgres cannot be reached,limits.on_store_error: localcounts in each replica with its share of each limit, anddenyanswers 503overloaded. by @raven-clown in #160 - Images in chat:
image_urlparts on/v1/chat/completions(a URL or adata:URL) and image blocks on/v1/messagesare translated to OpenAI, Anthropic and Gemini targets with text and images kept in order. A target that cannot take an image, such as Gemini with an image at a URL, is skipped. A translated inline image over 5 MiB is a 400image_too_large, and each image counts as 1,000 input tokens for limits until the provider reports usage (#41). by @raven-clown in #160 - OpenAI Responses API:
POST /v1/responsesis passed through to targets that speak the OpenAI API withmodelchanged andstoreset tofalse, streamed or not, so the Codex CLI and newer OpenAI SDK code work through transponder. Usage, with cached and reasoning tokens, is read from the final body or from the event that ends the stream, so usage headers, usage records, budgets, limits, access per route and fallback work as they do for chat. Anthropic, Gemini andechotargets, and servers without the endpoint, are skipped. Every caller of a route shares the provider account, so nothing is stored there andprevious_response_id,conversationanditem_referenceitems are refused with a 400unsupported: send the whole conversation ininput. A caller withllm.max_input_tokensgets a 400input_not_countablefor a storedpromptor aninput_file, which the limit could not measure; for other callers a file counts as 1,000 tokens like an image.background: trueis refused, since its result and usage could not be fetched through the gateway (#42). by @raven-clown in #160 - Every response, on the gateway's port and on
ops_listen_addr, carriesX-Content-Type-Options: nosniff, so a browser never runs an error body that quotes a caller's input as HTML. by @raven-clown in #160 - Every caller has one of the roles
admin,viewerormember, and the role of an API key now comes with the caller on each request, ready for the admin API and access per route. A key stored without a role is amemberand calls the gateway as before. by @raven-clown in #160 - Sign-in with OpenID Connect next to API keys: set
auth.oidc.issuerandauth.oidc.audience, and a JWT inAuthorization: Bearerorx-api-keyis checked for its signature, issuer, audience and expiry.user_claim(defaultsub),teams_claim(defaultgroups),roles_claimwithrole_mapping,jwks_urlandclock_skew(default 1m) map the token to a user, teams and a role. The issuer's keys are cached for an hour and read again for an unknown key id at most once every 10 seconds. With no keys fetched yet and the issuer down, token callers get 503auth_unavailableand/readyzreportsoidc. Whenrole_mappingnames anadmin, the first start no longer prints an admin key. by @raven-clown in #160 - Admin API under
/admin/v1/, described byapi/openapi.yamland served at/admin/v1/openapi.yaml:GET /status, API keys (GET,POST,PATCH,DELETEandPOST /keys/{name}/rotate, the secret shown once), usage totals grouped by user, team, key, project, model, provider, route or day (GET /usage), single usage records (GET /requests) and the audit log (GET /audit).viewermay read andadminmay write. Lists are cursor paginated, errors name the field, andIf-Matchwith the item'sversionrefuses a write over someone else's change with 409version_conflict. by @raven-clown in #160 - Providers, routes, budgets and limit profiles can be created, changed and deleted through the admin API (
/admin/v1/providers,/routes,/budgets,/profiles), so a new setup needs no YAML. Each write is live on the replica that took it before it answers and on every other replica within 2 seconds. A write that would leave a config that does not load is refused with 400invalid_configand the old one keeps serving. Deleting a provider a route uses is 409in_use. by @raven-clown in #160 - Provider keys sent to the admin API are sealed with AES-256-GCM under
secrets_key(TRANSPONDER_SECRETS_KEY) before they are stored, and reads only show whether one is set and its last four characters. With SQLite and nosecrets_key, one is generated intotransponder.keynext to the database; with Postgres it must be set, the same on every replica. by @raven-clown in #160 - The providers, routes, budgets and profiles of the YAML file are now stored at start and shown by the admin API as
managed_by_file, read-only there. Removing one from the file and restarting removes it. by @raven-clown in #160 - Audit log: every write through the admin API records who made it, what changed (the item before and after, without secrets), when, and the request id, in the same transaction as the write, on SQLite and Postgres. by @raven-clown in #160
GET /metricsserves Prometheus metrics:transponder_requests_total,transponder_request_duration_seconds,transponder_inflight_requests,transponder_limited_totalandtransponder_events_dropped_total, plustransponder_tokens_totalandtransponder_cost_usd_totalby provider and model,transponder_upstream_duration_seconds,transponder_fallbacks_total,transponder_unpriced_requests_total,transponder_config_reloads_totalandtransponder_build_info. No label carries a user, a key or a request id. On the gateway's port/metricsneeds a key or token with thevieweroradminrole. by @raven-clown in #160- Tracing over OTLP: set
otel.endpointto an OTLP/HTTP collector (port 4318) and each call is exported as one span with a child span for every provider it tried, carrying the provider, model, status, tokens and cost, and never prompt or completion text.otel.headersadds headers for a collector that needs a key, andotel.sample_ratiosamples the traces that start at the gateway. A caller'straceparentandtracestateare kept: the call joins the caller's trace and the provider is sent the attempt's span. Off by default. Anotel.endpointthat is not an http or https URL is now a config error, where it used to be ignored. by @raven-clown in #160 demo/:docker compose upstarts transponder in front of a fake provider with calls flowing through it, Prometheus, Jaeger, and a Grafana dashboard of requests, latency, tokens, c...
v0.2.4
What's Changed
Changed
- With limits on, a call reserves the price of its route's dearest target instead of the first one, so a free first target cannot let calls through that a paid fallback would bill. by @raven-clown in #106
POST /v1/messages/count_tokensgoes to the first Anthropic target of the route, wherever it is in the list. by @raven-clown in #106
Added
- xAI (Grok) provider (
type: xai) defaulting tohttps://api.x.ai/v1and sendingapi_keyas a bearer token. Abase_urlstill overrides that default. by @brevitywithorion in #101 - xAI reasoning tokens are counted apart from completion tokens, as in its chat completion usage, and priced at the output rate. by @brevitywithorion in #101
- Prices for grok-4.7, grok-4.6, grok-4.5 and grok-4.3, using the rate for a prompt under 200k tokens on the global endpoint. Longer prompts, and the US endpoint, cost more than these rates. by @brevitywithorion in #101
- Vercel AI Gateway provider (
type: vercel) defaulting tohttps://ai-gateway.vercel.sh/v1and sendingapi_keyas a bearer token. Abase_urlstill overrides that default. No prices are included, so calls are logged as unpriced. by @brevitywithorion in #102 - Fallback: a route's targets are tried in order, and the next one takes over when a target is unreachable, times out, answers 408, 429, a 5xx or 529, rejects the gateway's key, fails a stream before its first event, or cannot take the request. A request the provider rejects as wrong is not retried elsewhere, and nothing falls back once a byte has reached the caller. by @raven-clown in #106
- Cooldown: after
settings.cooldown_failures(3) failures in a row a target is tried last forsettings.cooldown(30s). by @raven-clown in #106 X-Transponder-Provider,X-Transponder-ModelandX-Transponder-Fallbackson routed responses, andfallbacksin the usage record. by @raven-clown in #106GET /v1/usageshows the caller what they have used and have left of each budget and token allowance that applies to them. by @raven-clown in #106
Fixed
- A tool call id made by Gemini is shortened to one OpenAI accepts when a later turn of the conversation goes to an OpenAI target. by @raven-clown in #106
New Contributors
- @brevitywithorion made their first contribution in #101
Full Changelog: v0.2.3...v0.2.4
v0.2.3
What's Changed
Changed
X-Usage-Output-Tokensno longer includes reasoning tokens for OpenAI and Gemini; they are inX-Usage-Reasoning-Tokens. by @raven-clown in #97- Token estimates count every non-Latin character as one and a half tokens, so Thai, CJK and other scripts are counted on the high side rather than undercounted. It is a heuristic; a model with a small vocabulary can still use more. by @raven-clown in #97
Added
- llama.cpp server provider (
type: llamacpp) defaulting tohttp://localhost:8080/v1and forwardingapi_keyas a bearer token. Targets usingllamacppcount as free in usage costs. Note thatllama-serverlistens on:8080by default, so pass--portor configurelisten_addrif running both on the same machine. by @nikhil-mewar in #96 - USD budgets per user (
user:*or an exact user), team and key, daily or monthly. A spent budget answers 402 with the subject, the limit and the reset time: codebudget_exceededfor OpenAI-dialect callers, and typebilling_errorwith codebudget_exceededfor Anthropic-dialect callers. by @raven-clown in #97 - Profiles in the shared mothership format, from the config or a shared
profiles_file, bound to keys, users and teams, with adefault_profile:requestsrate and concurrency,llm.tokensrate and daily and monthly allowances,llm.cost_usd, andllm.max_input_tokens,llm.max_output_tokensandllm.max_reasoning_tokens. Calls reserve before they run and settle after, and responses carryRateLimit-PolicyandRateLimitheaders. by @raven-clown in #97 - Reasoning tokens are counted apart where OpenAI and Gemini report them, priced at the output rate, stored with the usage and sent in
X-Usage-Reasoning-Tokens. by @raven-clown in #97 - Limit counters are rebuilt from this month's usage at start, so a restart does not reset anyone's spend. by @raven-clown in #97
Fixed
- Anthropic cache writes kept for an hour are priced at their own rate, twice the input price, instead of the five-minute rate. by @raven-clown in #97
Full Changelog: v0.2.2...v0.2.3
v0.2.2
What's Changed
Changed
- When a provider of another dialect rejects a translated request as invalid (a 4xx it would give again on a retry), the caller now gets that status and the provider's reason in its own dialect instead of a 502. by @raven-clown in #93
Added
GET /healthzanswers 200 while the process is up, andGET /readyzanswers 503 with the names of the dependencies that fail, such as{"status":"unavailable","failed":["store"]}, so Kubernetes and load balancers can restart the process or hold traffic. Neither needs an API key. by @raven-clown in #89POST /v1/messages, the Anthropic Messages API, so Claude Code and the Anthropic SDKs work with only a base URL change. Requests to Anthropic go through as sent, with only the model changed; streams are copied frame by frame and their usage is recorded. Requests to other providers are translated, tools included. by @raven-clown in #93POST /v1/messages/count_tokens, forwarded to the route's Anthropic target. by @raven-clown in #93- Anthropic provider (
type: anthropic). It forwards the caller'santhropic-versionandanthropic-beta. by @raven-clown in #93 - Gemini provider (
type: gemini) for chat, streams and embeddings through the Gemini API with an API key. by @raven-clown in #93 - OpenAI chat completions can now reach Anthropic and Gemini, and every translated call carries tools, tool calls and the system prompt. by @raven-clown in #93
- Prices for current Claude and Gemini models. by @raven-clown in #93
Full Changelog: v0.2.1...v0.2.2
v0.2.1
What's Changed
Added
transponder --check-updatelists the releases newer than the running one, how urgent they are and which changes touch the providers in your config. It only reads the release list and never installs anything. by @raven-clown in #84update_check: truelogs oneupdate availableline at start and once a day when a newer release is out. Off by default. by @raven-clown in #84- Releases come with binaries for Linux, macOS and Windows on amd64 and arm64, a
release.jsondescribing each change, and a container image atghcr.io/raven-clown/transponder. by @raven-clown in #84 - vLLM provider (
type: vllm) defaulting tohttp://localhost:8000/v1and forwardingapi_keyas a bearer token. Targets usingvllmcount as free in usage costs. by @nikhil-mewar in #85
Fixed
transponder --versionprints the commit and build time, as listed in 0.1.4. The helper was added then, but the flag still printed only the version. by @raven-clown in #83- Boolean config keys can be set from the environment, such as
TRANSPONDER_UPDATE_CHECK=true. Before, the value was read as text and the config failed to load. by @raven-clown in #84
Full Changelog: v0.2.0...v0.2.1
v0.2.0
Added
- OpenRouter provider (
type: openrouter) defaulting tohttps://openrouter.ai/api/v1. - An unknown provider
typein the config now lists the known types. GET /v1/modelslists the route names a caller can ask for, so clients such as Open WebUI can fill their model picker. Wildcard routes and the models a route sends upstream are left out.settings.attempt_timeout(default 60s) bounds how long a streamed call waits for its first event, andsettings.request_timeout(default 10m) bounds every call, streams included. Calls that are not streamed get only the request timeout, since a provider sends their headers once the whole answer is ready. Before, one 10 minute limit covered everything, so a stream that never started held the caller for 10 minutes.
Changed
- The
usercolumn of theusagetable is nowuser_id, sinceuseris a reserved word in Postgres. The migration runs at start and keeps every row; queries ontransponder.dbthat readuserneeduser_idinstead.
Fixed
- A provider stream that ends without
[DONE]now ends the caller's stream with an error event and estimated usage, instead of looking complete. - A stream line or event over 16 MiB ends the stream instead of growing memory.
v0.1.4
What's Changed
Added
- LiteLLM Proxy works as a provider. Set
type: litellmand transponder talks tohttp://localhost:4000/v1, or your ownbase_url, sendingapi_keyas a bearer token. by @nikhil-mewar in #78 type: ollamaproviders now sendapi_keyas a bearer token, so an Ollama behind an auth proxy or a hosted Ollama works instead of failing with 401. With no key, no header is sent. by @Satvik-jain in #75transponder --versionshows the commit and build time, for exampletransponder dev (1a2b3c4, 2026-11-04T10:00:00Z), plus, modifiedfor a dirty tree, so a bug report says exactly which build is running. by @Satvik-jain in #76
Fixed
- A chat request with a wrong field type now says what to fix, such as
max_tokens must be an integer, withparamset to the field, instead of a Go error naming internal types. It reads the same on every Go version. by @Satvik-jain in #77
New Contributors
- @Satvik-jain made their first contribution in #75
- @nikhil-mewar made their first contribution in #78
Full Changelog: v0.1.3...v0.1.4
v0.1.3
v0.1.2
v0.1.1
Fixed
- Preserve every data line when forwarding multiline streaming events.
Thanks to @snehaapratap for the fix in #28.