Quick Start

Quick Start

This guide gets you from a fresh checkout or release binary to a running local proxy with one configured upstream provider.

1. 1Install or build ProxAIUse a release binary or build the Rust project locally.
2. 2Run onceGenerate the app directory and local config files.
3. 3Configure one providerSet provider protocol, base_url, api_key, and default routing.
4. 4Connect a clientPoint the client base URL at the local proxy and send a small request.

Local endpoints

Endpoint	Default URL	Purpose
Proxy	http://127.0.0.1:18080	OpenAI-compatible and Anthropic-style request proxy
MCP	http://127.0.0.1:18081/mcp	Local MCP control surface

Some clients want the base URL without /v1; others want a full endpoint path. Use the client convention, but the proxy ultimately serves /v1/responses, /v1/chat/completions, and /v1/messages.

App directory

Runtime files are generated under the user app directory:

Platform	Path
Windows	%USERPROFILE%\.proxai\
Linux/macOS	~/.proxai/

Important files and folders:

• config.toml — local runtime configuration, intentionally git-ignored
• config.example.toml — generated example/reference
• logs/ — runtime logs
• captures/ — optional per-phase captures

Keep secrets local

Do not commit config.toml, API keys, logs, captures, or private prompt fixtures. The tracked repository should only contain sanitized examples.

Minimal provider config

Start with one provider and default routes for the inbound protocols you expect to use:

[routing.default_provider_names]
openai_responses = "openai"
openai_chat_completions = "openai"

[providers.openai]
protocol = "openai_responses"
base_url = "https://api.openai.com"
api_key = "..."

If your upstream speaks Anthropic Messages instead, set provider protocol = "anthropic_messages" and use the matching provider base URL/key. Supported protocol values are listed in Protocols.

Connect a client

Use the local proxy URL as your client base URL:

http://127.0.0.1:18080

For clients that require an API key in the UI, you can usually enter a dummy key. ProxAI forwards the provider key configured in config.toml instead of the client’s Authorization header for OpenAI-compatible providers.

Verify it works

Check	Expected result
Proxy starts	No config load error; local listener binds to 127.0.0.1:18080 by default
Client request reaches ProxAI	Logs show a compact request summary without private body content
Provider is selected	Route/default provider resolves to the configured provider name
Upstream responds	Client receives a protocol-compatible response or a compact upstream error

If a check fails, go to Troubleshooting and capture the narrowest useful phase for one sanitized request.

Next steps

ConfigurationTask-oriented config guide for providers, routes, captures, logging, and errors.RecipesCommon setup and debugging paths.Routing and ProvidersHow providers are selected and how protocols map to wire behavior.TroubleshootingSymptom cards with useful capture phases and next checks.