Install and Upgrade

Install and Upgrade

Use this page when you need the operational path: get a binary, run it locally, locate config, and upgrade without losing local state.

Runtime config stays local

config.toml is intentionally local and git-ignored. The tracked config.example.toml is the reference example; runtime config lives in your app directory.

Install path

1. 1Get a release binaryDownload the current ProxAI release for your platform or build locally from source.
2. 2Put it on PATHPlace the executable somewhere your shell and client launcher can find.
3. 3Start onceFirst run creates the app directory and local example files.
4. 4Edit config.tomlAdd providers, default provider names, and routes.
5. 5Connect the clientPoint OpenAI-compatible clients at the local ProxAI listener.

For a first request walkthrough, use Quick Start.

App directory

ProxAI stores local runtime state in the app directory. The exact path depends on platform and startup configuration.

Artifact	Purpose
`config.toml`	Local runtime configuration. Keep private and uncommitted.
`config.example.toml`	Generated local reference example. The repository copy remains canonical.
`captures/`	Optional local request/response artifacts for debugging. May contain private data.
`logs/`	Local diagnostic logs when configured.

See Environment and Files for exact file responsibilities.

Upgrade checklist

Check	Why it matters
Read release notes	Look for config, routing, protocol conversion, streaming, or error response changes.
Keep config.toml	Do not replace local private config with the example file.
Compare examples	Use the tracked config.example.toml as the single example source when adding new options.
Run a small request	Verify default provider routing before using large prompts or tools.
Check streaming if used	Streaming behavior is user-visible and should be tested with your real client.

Local source build

If you build from source, prefer the repository validation commands before replacing a working binary:

just check

For site-only changes, use:

just site check

When to revisit config

Add a providerAdd a named provider with protocol, base_url, and api_key.Route by modelUse explicit routes when one model pattern needs a provider or protocol override.Change error formatUse text for humans or JSON for SDK-style clients.Capture a requestEnable a narrow phase, reproduce once, then disable capture.

Safe rollback

Rollback is usually replacing the binary with the previous version while keeping the same local config.toml. If the newer version introduced config fields, remove only the fields that the older binary cannot parse.

Do not rollback captures into commits

Captures and logs can include prompts, tool arguments, outputs, provider payloads, and upstream identifiers. Keep them local unless deliberately sanitized.