pi-azfoundry-proxy

A small local proxy that lets the Pi coding agent work with Azure OpenAI deployments through an OpenAI-compatible /v1 interface.

This project is especially useful if you want to use newer or frontier models through Azure AI Foundry, while your Azure deployment setup needs to run in West Europe. The proxy gives Pi a simple local endpoint and forwards requests to the correct Azure deployment.

Why this exists

Pi expects an OpenAI-style Chat Completions API. Azure OpenAI uses deployment-specific endpoints and api-key authentication. This proxy bridges that difference.

• Pi sends requests to http://127.0.0.1:8787/v1
• the proxy translates them to the correct Azure OpenAI deployment endpoint
• your Azure API key stays in a local .env file

┌──────┐   OpenAI-style    ┌──────────────────────┐   Azure-style    ┌───────────────┐
│  Pi  │ ───────────────▶ │  azure-openai-proxy  │ ───────────────▶ │ Azure OpenAI  │
│ CLI  │  127.0.0.1:8787   │      (Node.js)       │   api-key header │  deployment   │
└──────┘                   └──────────────────────┘                   └───────────────┘

Features

• OpenAI-compatible local /v1 endpoint for Pi
• Routes model aliases to Azure OpenAI deployments
• Supports multiple deployments through one local proxy
• Keeps Azure credentials out of Pi config
• Simple single-file Node.js setup

Requirements

• Node.js 20.6 or newer
• Pi CLI
• An Azure OpenAI resource
• At least one Azure OpenAI deployment
• An Azure OpenAI API key

Install Pi if needed:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Quick start

1. Clone the repository

git clone https://github.com/<your-user>/pi-azfoundry-proxy.git
cd pi-azfoundry-proxy

2. Create .env

Linux / macOS

cp .env.example .env
chmod 600 .env
$EDITOR .env

Windows (PowerShell)

Copy-Item .env.example .env
notepad .env

Set these values:

• AZURE_OPENAI_API_KEY
• AZURE_OPENAI_BASE_URL
• AZURE_OPENAI_DEPLOYMENTS

Optional:

• AZURE_OPENAI_API_VERSION
• AZURE_OPENAI_DEPLOYMENT for legacy single-deployment mode
• PORT (default: 8787)

3. Configure Pi

Create ~/.pi/agent/models.json.

On Windows:

%USERPROFILE%\.pi\agent\models.json

Example:

{
  "providers": {
    "azure-openai-proxy": {
      "baseUrl": "http://127.0.0.1:8787/v1",
      "api": "openai-completions",
      "apiKey": "dummy",
      "authHeader": true,
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false,
        "supportsStore": false,
        "supportsUsageInStreaming": true,
        "maxTokensField": "max_tokens"
      },
      "models": [
        {
          "id": "fast",
          "name": "Fast general-purpose coding model",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 4096,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        },
        {
          "id": "coding",
          "name": "Primary coding model",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 8192,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        },
        {
          "id": "openspec",
          "name": "Reasoning-focused model",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 8192,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}

apiKey is intentionally set to "dummy" because the real Azure credential is read from .env by the proxy.

4. Start the proxy

npm start

Expected output:

Azure OpenAI proxy listening on http://127.0.0.1:8787/v1
Model routing:
  fast -> gpt-5-mini
  openspec -> gpt-5.5
  coding -> gpt-5.4

5. Start Pi

pi --provider azure-openai-proxy --model fast

You can switch models later with Pi's /model command.

Environment variables

Required

• AZURE_OPENAI_API_KEY
  Your Azure OpenAI API key.

• AZURE_OPENAI_BASE_URL
  Your Azure resource base URL, for example:
  https://your-resource.cognitiveservices.azure.com

• AZURE_OPENAI_DEPLOYMENTS
  A JSON object that maps Pi model IDs to Azure deployment names.

  Example:

  AZURE_OPENAI_DEPLOYMENTS={"fast":"gpt-5-mini","coding":"gpt-5.4","openspec":"gpt-5.5"}

Optional

• AZURE_OPENAI_API_VERSION
  Defaults to 2024-12-01-preview.

• AZURE_OPENAI_DEPLOYMENT
  Legacy single-deployment fallback.

• PORT
  Local port for the proxy. Defaults to 8787.

Notes

• In multi-model mode, the proxy only accepts model IDs defined in AZURE_OPENAI_DEPLOYMENTS.
• In single-model mode, all requests are forwarded to AZURE_OPENAI_DEPLOYMENT.
• The proxy listens only on 127.0.0.1 by default.

Troubleshooting

Problem	Likely fix
Missing AZURE_OPENAI_API_KEY	Add the key to .env.
Missing AZURE_OPENAI_BASE_URL	Set the Azure resource URL in .env.
Missing AZURE_OPENAI_DEPLOYMENTS or AZURE_OPENAI_DEPLOYMENT	Configure either multi-model or single-model mode.
unknown provider in Pi	Check the provider name in ~/.pi/agent/models.json.
EADDRINUSE	Change PORT and update the Pi baseUrl accordingly.
401 or 403 from Azure	Verify your API key and Azure resource URL.
404 or deployment not found	Check the deployment names in .env.
invalid JSON for AZURE_OPENAI_DEPLOYMENTS	Make sure the value is valid JSON, not JavaScript object syntax.

License

This project is licensed under the terms of the MIT License.