pi-openai-proxy

A local OpenAI-compatible HTTP proxy built on pi's SDK. Routes requests through pi's multi-provider model registry and credential management, exposing a single http://localhost:4141/v1/... endpoint that any OpenAI-compatible client can connect to.

Why

• Single gateway to 20+ LLM providers (Anthropic, OpenAI, Google, Bedrock, Mistral, xAI, Groq, OpenRouter, Vertex, etc.) via one OpenAI-compatible API
• No duplicate config — reuses pi's ~/.pi/agent/auth.json and models.json for credentials and model definitions
• Self-hosted — runs locally, no third-party proxy services
• Streaming — full SSE streaming with token usage and cost tracking
• Strict validation — unsupported parameters are rejected clearly, not silently ignored

Prerequisites

1. pi must be installed
2. At least one provider must be configured via pi /login
3. Bun (for development) or Node.js >= 20 (for production)

Installation

# Install globally
npm install -g @victor-software-house/pi-openai-proxy

# Or run directly with npx
npx @victor-software-house/pi-openai-proxy

Quickstart

# Start the proxy (defaults to http://127.0.0.1:4141)
pi-openai-proxy

List available models

curl http://localhost:4141/v1/models | jq '.data[].id'

Chat completion (non-streaming)

curl http://localhost:4141/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-20250514",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Chat completion (streaming)

curl http://localhost:4141/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Tell me a joke"}],
    "stream": true
  }'

Use with any OpenAI-compatible client

Point any client that supports OPENAI_API_BASE (or equivalent) at http://localhost:4141/v1:

# Example: Aider
OPENAI_API_BASE=http://localhost:4141/v1 aider --model anthropic/claude-sonnet-4-20250514

# Example: Continue (in settings.json)
# "apiBase": "http://localhost:4141/v1"

# Example: Open WebUI
# Set "OpenAI API Base URL" to http://localhost:4141/v1

Model resolution

The proxy resolves model references in this order:

1. Exact public ID match — the ID from GET /v1/models
2. Canonical ID fallback — provider/model-id format (only for exposed models)

With the default collision-prefixed mode and no collisions, model IDs are exposed without prefixes:

curl http://localhost:4141/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hi"}]}'

Supported Endpoints

Endpoint	Description
GET /v1/models	List exposed models (filtered by exposure mode, only those with configured credentials)
GET /v1/models/{model}	Model details by public ID or canonical ID (supports URL-encoded IDs with /)
POST /v1/chat/completions	Chat completions (streaming and non-streaming)

Supported Chat Completions Features

Feature	Notes
model	Public ID, canonical (provider/model-id), or collision-prefixed shorthand
messages (text)	system, developer, user, assistant, tool roles
messages (base64 images)	Base64 data URI image content parts (image/png, image/jpeg, image/gif, image/webp)
stream	SSE with text_delta and toolcall_delta mapping
temperature	Direct passthrough
max_completion_tokens	Preferred; max_tokens accepted as deprecated fallback
stop	Via passthrough
user	Via passthrough
stream_options.include_usage	Final usage chunk in SSE stream
tools / tool_choice	JSON Schema -> TypeBox conversion (supported subset); tool_choice translated per-provider
tool_calls in messages	Assistant tool call + tool result roundtrip
parallel_tool_calls	Forwarded to OpenAI/Codex; translated to disable_parallel_tool_use for Anthropic
reasoning_effort	Maps to pi's ThinkingLevel (none, minimal, low, medium, high, xhigh)
response_format	text, json_object, and json_schema (OpenAI-compatible APIs only)
top_p	Supported by OpenAI, Anthropic (native), and Google (translated to topP)
frequency_penalty	OpenAI and Google only (translated to frequencyPenalty)
presence_penalty	OpenAI and Google only (translated to presencePenalty)
seed	OpenAI and Google only (translated to nested generationConfig.seed)
stop	Translated per-provider (stop_sequences for Anthropic, stopSequences for Google)
metadata	OpenAI passthrough; arbitrary keys silently skipped for other providers
prediction	OpenAI passthrough only (speculative decoding)

Not supported: n > 1, logprobs, logit_bias, remote image URLs (disabled by default).

Provider-aware field translation

Fields are translated to each provider's native format, not blindly forwarded:

• OpenAI / Mistral: All fields passed directly (same wire format)
• Codex (Responses API): Only tool_choice and parallel_tool_calls (other fields rejected by API)
• Anthropic: tool_choice → { type } format, stop → stop_sequences, user → metadata.user_id, parallel_tool_calls: false → disable_parallel_tool_use
• Google: Nested into generationConfig with camelCase names (topP, stopSequences, seed, etc.)

Fields that have no equivalent in a target provider are silently skipped — the request succeeds and the provider's default applies.

Model Naming and Exposure

Public model IDs

The proxy generates public model IDs based on a configurable ID mode:

Mode	Behavior	Example
collision-prefixed (default)	Raw model IDs; prefix only providers that share a model name	gpt-4o or openai/gpt-4o if codex also has gpt-4o
universal	Raw model IDs only; rejects config if duplicates exist	gpt-4o, claude-sonnet-4-20250514
always-prefixed	Always <prefix>/<model-id>	openai/gpt-4o, anthropic/claude-sonnet-4-20250514

The collision-prefixed mode prefixes all models from providers that form a connected conflict group (not just the colliding model names).

Exposure modes

Control which models appear in the API:

Mode	Behavior
all (default)	Expose every model with configured credentials
scoped	Expose models from selected providers only (scopedProviders)
custom	Expose an explicit allowlist of canonical IDs (customModels)

Canonical model IDs

Internal canonical IDs use the provider/model-id format matching pi's registry:

anthropic/claude-sonnet-4-20250514
openai/gpt-4o
google/gemini-2.5-pro
xai/grok-3
openrouter/anthropic/claude-sonnet-4-20250514

Canonical IDs are accepted as backward-compatible fallback in requests, but only for models that are currently exposed. Hidden models cannot be reached by canonical ID.

Configuration

What comes from pi

The proxy reads two files from pi's configuration directory (~/.pi/agent/):

File	Managed by	What the proxy uses
auth.json	pi /login	API keys for each provider (Anthropic, OpenAI, Google, etc.)
models.json	pi built-in + user edits	Model definitions, capabilities, and pricing

The proxy does not read pi's settings.json (installed packages, enabled extensions) or session-level model filters (--models flag). All models with configured credentials are exposed through the proxy, regardless of pi session scope.

What the proxy adds

Proxy-specific settings are configured via environment variables or the /proxy config panel (when installed as a pi package):

Setting	Env variable	Default	Description
Bind address	PI_PROXY_HOST	127.0.0.1	Network interface (127.0.0.1 = local only, 0.0.0.0 = all)
Port	PI_PROXY_PORT	4141	HTTP listen port
Auth token	PI_PROXY_AUTH_TOKEN	(disabled)	Bearer token for proxy authentication
Remote images	PI_PROXY_REMOTE_IMAGES	false	Allow remote image URL fetching
Max body size	PI_PROXY_MAX_BODY_SIZE	52428800 (50 MB)	Maximum request body size in bytes
Upstream timeout	PI_PROXY_UPSTREAM_TIMEOUT_MS	120000 (120s)	Upstream request timeout in milliseconds

Model exposure settings are configured via the JSON config file (~/.pi/agent/proxy-config.json):

Setting	Default	Description
publicModelIdMode	collision-prefixed	Public ID format: collision-prefixed, universal, always-prefixed
modelExposureMode	all	Which models to expose: all, scoped, custom
scopedProviders	[]	Provider keys for scoped mode
customModels	[]	Canonical model IDs for custom mode
providerPrefixes	{}	Provider key -> custom prefix label overrides

When used as a pi package, all settings are persisted in ~/.pi/agent/proxy-config.json and applied when the extension spawns the proxy.

Discovering available models

List all models the proxy exposes (filtered by the active exposure mode):

curl http://localhost:4141/v1/models | jq '.data[].id'

Model objects follow the standard OpenAI shape (id, object, created, owned_by) with no proprietary extensions.

Per-request API key override

The X-Pi-Upstream-Api-Key header overrides the registry-resolved API key for a single request. This keeps Authorization available for proxy authentication:

curl http://localhost:4141/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Pi-Upstream-Api-Key: sk-your-key-here" \
  -d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hi"}]}'

Proxy authentication

Set PI_PROXY_AUTH_TOKEN to require a bearer token for all requests:

PI_PROXY_AUTH_TOKEN=my-secret-token pi-openai-proxy

# Clients must include the token
curl http://localhost:4141/v1/models \
  -H "Authorization: Bearer my-secret-token"

API compatibility

The proxy implements a subset of the OpenAI Chat Completions API. Request and response shapes match the OpenAI specification for supported fields. Unsupported fields are rejected with 422 and an OpenAI-style error body naming the offending parameter.

There is no OpenAPI/Swagger spec for the proxy itself. Use the OpenAI API reference as the primary documentation, noting the supported subset listed in this README.

Pi Integration

Install as a pi package to get the /proxy command family and --proxy flag:

pi install npm:@victor-software-house/pi-openai-proxy

Command family

/proxy               Open the settings panel
/proxy start         Start the proxy server
/proxy stop          Stop the proxy server (session-managed only)
/proxy status        Show proxy status
/proxy config        Open the settings panel
/proxy show          Summarize current configuration
/proxy path          Show config file location
/proxy reset         Restore default settings
/proxy help          Show usage

Settings panel

/proxy (or /proxy config) opens an interactive settings panel where you can configure the bind address, port, auth token, remote images, body size limit, and upstream timeout. Changes are saved to ~/.pi/agent/proxy-config.json immediately. Restart the proxy to apply changes.

Standalone (background) mode

For a proxy that outlives pi sessions, run the binary directly:

# Foreground
pi-openai-proxy

# Background
pi-openai-proxy &

# With custom port
PI_PROXY_PORT=8080 pi-openai-proxy &

The extension detects externally running instances and shows their status via /proxy status without trying to manage them.

Architecture

┌─────────────────────────────┐         ┌──────────────────────────────────┐
│       HTTP Client           │         │        pi-openai-proxy           │
│  (curl, Aider, Continue,    │         │                                  │
│   LiteLLM, Open WebUI, etc.)│         │  ┌────────────────────────────┐  │
└─────────────┬───────────────┘         │  │     Hono HTTP Server       │  │
              │                         │  │  ├─ Request parser         │  │
              │  POST /v1/chat/         │  │  ├─ Message converter      │  │
              │  completions            │  │  ├─ Model resolver         │  │
              ├────────────────────────►│  │  ├─ Tool converter         │  │
              │                         │  │  └─ SSE encoder            │  │
              │  GET /v1/models         │  └────────────────────────────┘  │
              ├────────────────────────►│                                  │
              │                         │  ┌────────────────────────────┐  │
              │                         │  │        Pi SDK              │  │
              │  SSE / JSON             │  │  ├─ ModelRegistry          │  │
              │◄────────────────────────┤  │  ├─ AuthStorage            │  │
              │                         │  │  ├─ streamSimple()         │  │
                                        │  │  └─ completeSimple()       │  │
                                        │  └────────────────────────────┘  │
                                        └──────────────────────────────────┘

Pi SDK layers used

• @mariozechner/pi-ai — streamSimple(), completeSimple(), Model, Usage, AssistantMessageEvent
• @mariozechner/pi-coding-agent — ModelRegistry, AuthStorage

Security defaults

• Binds to 127.0.0.1 (localhost only) by default
• Remote image URLs disabled by default
• Request body size limited to 50 MB
• Upstream timeout of 120 seconds
• Secrets are never included in error responses
• Client disconnects abort upstream work immediately

Dev Workflow

bun install           # Install dependencies
bun run dev           # Run in development
bun run build         # Build for npm (tsdown)
bun run typecheck     # TypeScript strict check
bun run lint          # Biome + oxlint (strict)
bun test              # Run all tests

Tooling

• Bun — runtime, test runner, package manager
• tsdown — npm build (ESM + .d.ts)
• Biome — format + lint
• oxlint — type-aware lint with strict rules (.oxlintrc.json)
• lefthook — pre-commit hooks (format, lint, typecheck), pre-push hooks (test)
• commitlint — conventional commits
• semantic-release — automated versioning and npm publish
• mise — tool version management (node, bun)

License

MIT