Documentation
ProxAI Documentation
Section titled “ProxAI Documentation”ProxAI is a small local compatibility proxy for OpenAI-compatible requests. It accepts local OpenAI-compatible traffic, normalizes specific upstream-breaking request shapes, routes to explicit providers, and translates between supported protocols when configured.
One request through ProxAI
Section titled “One request through ProxAI”Start here
Section titled “Start here”Install and run locallyFastest path from a fresh machine to a running local proxy and editable config.toml.Add or route a providerRoute by model, request protocol, provider protocol, and upstream model rewrite.Debug a failed requestCommon symptoms, likely causes, next checks, and where to inspect logs/captures.Understand protocol behaviorProtocol values, request paths, pass-through/conversion paths, and interaction examples.
Choose your path
Section titled “Choose your path”Using ProxAI
Task-oriented pages for running, configuring, routing, observing, and troubleshooting the local proxy.
User view
Protocol Guide
Protocol concepts, supported wire behaviors, streaming expectations, and per-protocol interaction examples.
Protocol view
Developer Guide
Internal architecture, module boundaries, conversion design, streaming internals, and error rendering.
Maintainer view
Reference
Exact configuration reference, CLI flags, defaults, protocol values, error payloads, and behavior contracts.
Lookup view
Using ProxAI
Section titled “Using ProxAI”Quick startRun ProxAI locally, find the app directory, edit config.toml, and connect a client.Install and upgradeGet a binary, locate local runtime files, upgrade safely, and roll back without losing config.Client integrationBase URL, endpoints, local API keys, model routing, error format, and streaming clients.Set up a providerProvider names, protocols, base URLs, API keys, defaults, and explicit routes.Try common recipesTask-oriented paths for provider setup, model routing, safe captures, and streaming diagnosis.ConfigurationServer listeners, routing, providers, capture, logging, and error response behavior.Routing and providersHow routes select providers and how provider protocol controls outbound wire behavior.ObservabilityLogs, captures, request hints, and privacy boundaries for local debugging.Streaming and toolsUser-facing guide to terminal events, tool-call stalls, and timeout layers.Debugging workflowStep-by-step workflow for classifying failures, capturing one phase, and sharing sanitized evidence.TroubleshootingCommon symptoms, likely causes, and next checks across requests, providers, and streaming.
Protocol Guide
Section titled “Protocol Guide”Protocol overviewProtocol values, pipeline phases, supported runtime paths, and per-protocol walkthroughs.Choose a protocolDecide inbound and provider protocols before configuring pass-through or conversion routes.Lossiness and fidelityUnderstand pass-through, supported conversion, lossy mappings, and higher-fidelity protocol choices.OpenAI ResponsesItemized output, stable item ids, hosted tools, and typed streaming events.OpenAI Chat CompletionsChoices, assistant messages, tool call chunks, finish reasons, and `[DONE]`.Anthropic MessagesMessage envelope, flat content blocks, stop reasons, and content block streams.Streaming behaviorClient-visible streaming expectations, terminal events, and stalled tool-call timeouts.
Developer Guide
Section titled “Developer Guide”ArchitectureRequest lifecycle, module boundaries, pipeline phases, and how protocol translation fits into the proxy.Module boundariesWhere parsing, routing, translation, provider behavior, HTTP carriers, errors, and observation belong.Config flowHow config.toml, examples, CLI overrides, validation, providers, and runtime state fit together.Error flowHow internal errors become compact client-facing HTTP and SSE errors.Protocol conversionPair-oriented conversion rules, wire-model alignment, SDK comparison, and streaming identifier models.Streaming internalsCarrier, BodyObserver, SSE scanner, and protocol state machines.Error handling internalsTyped errors, ErrorResponseSpec, fields, payload, and HTTP/SSE rendering.Contributor checklistOperational checklist for runtime settings, conversion pairs, streaming, errors, tests, and docs.
Reference
Section titled “Reference”Configuration referenceSingle-source config.example.toml reference and links to field explanations and defaults.CLIRuntime flags, route overrides, capture subcommands, and default endpoints.Defaults and limitsDefault endpoints, timeouts, concurrency, body size, and capture defaults.ProtocolsProtocol values, request paths, accepted locations, and supported conversion pairs.Compatibility matrixProtocol-pair support for request, response, streaming, tools, reasoning, and known lossiness.Route matchingExact route matching outcomes, protocol guards, model patterns, and fallback behavior.Capture phasesPhase boundaries, config switches, CLI phase names, and privacy risks.Environment and filesApp directories, generated runtime files, repository docs, and local artifact boundaries.Error responsesClient-facing payload, type enum, HTTP status semantics, and preserved headers.Status and stop reasonsMap stop_reason, finish_reason, status, and streaming terminal events across protocols.Behavior ContractsStable promises ProxAI commits to across versions.GlossaryShared terminology for protocols, phases, routing, providers, streaming, captures, and errors.