pi-gateway: point any OpenAI client at one local URL (127.0.0.1:4000) and reach every model pi can route to — Anthropic, OpenAI, Google, Mistral, Bedrock, Vertex, plus OAuth subscriptions like Claude Pro, ChatGPT Codex, GitHub Copilot, and Gemini CLI

npm version CI License: MIT

OpenAI-compatible local API on top of pi.dev. LiteLLM-shape stateless protocol translator. Re-exposes every model pi can reach (Anthropic, OpenAI, Google, Mistral, Bedrock, Vertex, plus OAuth subscriptions like Claude Pro / ChatGPT Codex / GitHub Copilot / Gemini CLI) through POST /v1/chat/completions + GET /v1/models, so Open WebUI / LibreChat / Cursor / Continue.dev / Cline can use them without re-entering credentials.

Two install paths from one package:

pnpm dlx pi-gateway --port 4000
# or globally
npm i -g pi-gateway && pi-gateway --port 4000

Runs in the foreground; Ctrl+C to stop.

Add to ~/.pi/agent/settings.json:

{
 "packages": [
 "git:git@github.com:bntvllnt/pi-gateway"
 ]
}

Restart pi. Then inside pi:

/gateway:start # spawn the daemon (detached, survives pi exit)
/gateway:status # show url + pid + model count
/gateway:stop # SIGTERM the daemon

Point any OpenAI-compatible client at http://127.0.0.1:4000/v1. The API key field accepts any non-empty string on loopback.

# librechat.yaml
endpoints:
 custom:
 - name: "pi-gateway"
 baseURL: "http://127.0.0.1:4000/v1"
 apiKey: "pi-gateway"
 models:
 fetch: true

{
 "models": [{
 "provider": "openai",
 "apiBase": "http://127.0.0.1:4000/v1",
 "apiKey": "pi-gateway",
 "model": "anthropic/claude-sonnet-4-5",
 "title": "Claude via pi-gateway"
 }]
}

Out of scope for v1: /v1/responses, /v1/embeddings, /v1/images/generations, /v1/audio/*, /v1/messages (Anthropic Messages format).

Is: a stateless HTTP frontend. Validates → resolves model → resolves auth → calls pi-ai.complete() or pi-ai.stream() → translates back into OpenAI Chat Completions shape (JSON or SSE).

Is not:

• ❌ A pi agent. No pi AgentSession is created.
• ❌ A prompt injector. What the client sends is what pi-ai sees — no system prompt, no tools, no skills are added.
• ❌ A tool runner. tools and tool_choice are forwarded; the client executes and posts role: "tool" results.
• ❌ A conversation store. Each POST /v1/chat/completions is independent.

No --api-key flag. Argv leaks via /proc/<pid>/cmdline + ps aux. Set the key in ~/.pi/agent/gateway.json ({ "apiKey": "..." }) or via PI_GATEWAY_API_KEY env var.

Subcommands:

pi-gateway models # Print available models then exit
pi-gateway --help
pi-gateway --version

• Default bind: 127.0.0.1. server.address() is asserted after listening so a refactor can't silently bind 0.0.0.0.
• Non-loopback bind requires apiKey in the config file. CLI flag is refused.
• PID lockfile at ~/.pi/agent/gateway.pid via atomic O_CREAT|O_EXCL. Single instance enforced; stale files cleaned automatically.
• OAuth subscriptions default-allow on loopback (so Claude Pro / Codex work from Open WebUI), default-deny on non-loopback unless --expose-oauth-subscriptions.
• Loopback Host-header guard — requests to a loopback bind with an unexpected Host return HTTP 403, blocking DNS-rebinding from browser-based clients on the same machine.
• Request body cap — payloads over 16 MB return HTTP 413.
• Access log redacts everything outside a hardcoded allowlist (content-type, content-length, user-agent, accept, accept-encoding, host). No authorization / token / key headers in logs.

import { startServer, stopServer } from "pi-gateway";
import { DEFAULT_CONFIG } from "pi-gateway/config"; // future export
const handle = await startServer({
 config: { ...DEFAULT_CONFIG, port: 0, bindAddress: "127.0.0.1" },
});
const url = `http://${handle.address.address}:${handle.address.port}`;
const r = await fetch(`${url}/v1/chat/completions`, { method: "POST", /* ... */ });
await stopServer(handle);

Used by the test suite to bind real listeners on 127.0.0.1:0 without invoking the binary.

git clone https://github.com/bntvllnt/pi-gateway.git
cd pi-gateway
pnpm install
pnpm run check # lint + typecheck + build + smoke + e2e + contract

Quality gates:

All gates run on pre-commit and CI.

schemas/openresponses.openapi.json pins https://www.openresponses.org/openapi/openapi.json (OpenAI API v2.3.0, 108 component schemas) in-repo to avoid drift. The contract test loads this file and rejects any response that doesn't match.

MIT © bntvllnt

• CHANGELOG.md — release notes; tags link to the matching section
• llms.txt — short hub for AI consumption
• llms-full.txt — full reference for AI consumption
• CLAUDE.md — project rules + contract guarantees
• pi.dev — the underlying agent runtime
• pi-claude-code, pi-git-worktrees — sibling pi extensions