triproxy: Transparent LLM Gateway for Using Any Model with OpenAI SDK, Codex, Claude Code, and Chat Clients

Overview

triproxy is a Go‑written, headless HTTP gateway that provides lossless, bidirectional conversion among the three dominant LLM protocols: Chat Completions, Responses, and Messages. It handles request bodies, response bodies, SSE streaming, and encrypted reasoning items, allowing any client that speaks one of these protocols to communicate with any upstream model provider.

Problem Statement

Many developers use multiple LLM tools—OpenAI SDK, Codex CLI, Claude Code—each of which expects a different protocol ( Responses for Codex, Messages for Claude Code, Chat Completions for OpenAI). Most model providers expose only a single protocol endpoint, forcing users to maintain separate configurations for each client.

Solution Architecture

triproxy sits between clients and upstream providers, performing three‑step processing for each request:

Routing & Parsing : The incoming URL http://localhost:8866/{alias}/v1/… is parsed by protoFromPath() to determine the client protocol. The alias configuration supplies the upstream base URL and the upstream protocol ( Alias.Protocol).

Concurrency Control : A per‑alias semaphore limits simultaneous requests. When the limit is exceeded, the reject mode returns HTTP 429 immediately, while the queue mode queues the request.

Conversion & Forwarding : If the client and upstream protocols differ, the request is parsed into a unified Req structure, then emitted as the appropriate upstream request. Header adaptation removes provider‑specific headers (e.g., openai-*, anthropic-beta) and injects required ones (e.g., anthropic-version: 2023-06-01). API keys are passed through unchanged.

Responses follow a similar path: upstream data is parsed into a unified Resp (or streamEv for SSE), then encoded back to the client protocol. Streamed responses are converted event‑by‑event, preserving ordering and flushing each event to avoid client stalls.

Key Features

Three‑Protocol Bidirectional Conversion : Full request/response body mapping, including SSE streams, tool_calls / tool_use / function_call handling, usage counting, and sampling parameters.

Zero‑Loss Transparent Pass‑Through : When client and upstream protocols match, the gateway forwards the payload unchanged.

API Key Pass‑Through : No key storage or modification; the original Authorization or x‑api‑key header is relayed directly.

Thinking Bridge : Encrypted reasoning from OpenAI Responses is wrapped in a triproxy‑reasoning‑v1: prefix and placed into the Anthropic thinking block, preserving encrypted content across protocol boundaries.

Concurrency Modes : reject (immediate 429) or queue (FIFO) for overload protection.

Custom Header Injection : Users can supply arbitrary headers (e.g., custom User‑Agent) to masquerade as a specific client.

Proxy Support : Per‑alias or global HTTP/HTTPS/SOCKS5 proxies.

Deployability : Single binary, Docker image, systemd service, or install.sh script; cross‑compiled for 15 platforms (x86, ARM, RISC‑V, etc.).

Configuration

Configuration is a YAML (or JSON) file. Each alias defines:

aliases:
  llm:
    upstream: "https://chat.sample.com"
    protocol: openai-chat
    max_concurrency: 0   # 0 = unlimited, recommended 2‑4
    concurrency_mode: reject   # or queue
    headers:
      User-Agent: "claude-cli/2.1.221 (external, cli)"
      x-app: "cli"
      anthropic-beta: "claude-code-20250219"
      thinking: true

Short names ( chat, responses, messages) are automatically normalized to the full protocol identifiers.

Comparison with cc‑switch

Scope : triproxy focuses solely on protocol translation; cc‑switch provides a full desktop UI for provider management, prompts, skills, and usage tracking.

Technology Stack : triproxy is pure Go; cc‑switch is Rust + Tauri.

Deployment : triproxy runs as a headless service (binary, Docker, systemd); cc‑switch runs as a GUI application on Windows/macOS/Linux.

Features : triproxy offers API‑key pass‑through, SSE conversion, and encrypted reasoning bridge. cc‑switch offers multi‑provider presets, failover, health monitoring, and cloud sync.

Resource Usage : triproxy idles at ~6 MiB; cc‑switch requires a resident GUI process.

Quick Start

Install :

# Build from source
go build -o triproxy .

# Docker
docker run -d --name triproxy \
  -p 8866:8866 \
  -v /path/to/config.yaml:/etc/triproxy/config.yaml \
  tomoncle/triproxy

# Systemd (root)
sudo ./install.sh

Run : ./triproxy -config config.yaml Health Check : curl http://localhost:8866/healthz Use with Clients :

# Codex CLI (Chat Completions upstream)
export OPENAI_BASE_URL="http://localhost:8866/llm/v1"
export OPENAI_API_KEY="your_key"
codex

# Claude Code (Anthropic Messages upstream)
export ANTHROPIC_BASE_URL="http://localhost:8866/llm"
export ANTHROPIC_API_KEY="your_key"
claude

Typical Use Cases

Teams that use multiple LLM clients (OpenAI SDK, Codex, Claude Code) but have a single‑protocol upstream model.

Third‑party models that expose only one protocol; triproxy enables them to be accessed by any client without code changes.

Server‑side deployments where a lightweight, headless proxy is preferred over a GUI tool.

Conclusion

triproxy provides a minimal, extensible solution for unifying LLM protocol interactions. By abstracting protocol differences into a common request/response model and handling streaming, encrypted reasoning, and concurrency, it lets developers and teams use any LLM model with any existing client, simplifying integration and reducing operational friction.