feature: Looking for protocol conversion and docs suggestion

[fyq163]

The Problem

Currently, the documentation does not clearly state whether Aperture translates between different LLM API formats (e.g., OpenAI /v1/chat/completions ↔ Anthropic /v1/messages).

I mistakenly assumed Aperture could accept an OpenAI-style request and convert it to an Anthropic-style request before forwarding it to the backend. However, after testing, it seems Aperture simply acts as a passthrough proxy and forwards the request as-is. This leads to confusion and failed requests when the client format doesn't match the backend format.

The Request

1. Docs Update (Primary): Please add a prominent note in the documentation explaining that Aperture is a passthrough proxy and does not perform protocol conversion. Clients must use the native request format of the target provider (e.g., Anthropic format for Anthropic backends, OpenAI format for OpenAI backends).
2. Feature Request (Secondary): As a future enhancement, it would be great if Aperture could optionally translate request/response formats (e.g., accept OpenAI input, convert and forward as Anthropic). This would allow tools locked to a specific API format (like Claude Code or OpenAI Codex CLI) to seamlessly use different backends without needing an external conversion proxy.

[guygrigsby]

@fyq163 Aperture does support internal format translation and those docs can be found at https://tailscale.com/docs/aperture/provider-compatibility.

[lorengordon]

I'm with @fyq163 . I've tested this, and there does not seem to be any working format translation in Aperture. The docs seem to agree:

The compatibility object in a provider configuration specifies which API formats the provider supports. These flags determine which endpoints Aperture exposes for the provider's models.

If you expose an endpoint via Aperture that the provider does not support, the request will fail.

[guygrigsby]

My mistake. Will open this back up.