Using Pi with SoAI

Pi can use SoAI through a custom OpenAI-compatible model catalog. Pi deliberately does not include an MCP client, so this integration covers model inference.

Configure model access

In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, and open OpenAI. This tab appears only to an Administrator with API key management (OPENAI_API_ADMIN). Select Create key and copy the key when it is shown. Then open Models and copy the exact ID of a model that supports Chat Completions and has enough context and tool capability for the intended workflow. This requires Model read access (MODEL_READ).

Add SoAI to Pi's model catalog

Add a provider to ~/.pi/agent/models.json. Pi supports environment-variable substitution in apiKey; keep the secret in the environment. 

{
  "providers": {
    "soai": {
      "baseUrl": "https://SOAI_HOST:5090/v1",
      "apiKey": "${SOAI_OPENAI_API_KEY}",
      "api": "openai-completions",
      "models": [
        {
          "id": "YOUR_MODEL_ID",
          "name": "SoAI model",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 65536,
          "maxTokens": 4096
        }
      ]
    }
  }
}
export SOAI_OPENAI_API_KEY='YOUR_SOAI_API_KEY'
export NODE_EXTRA_CA_CERTS='/path/to/soai-ca.pem'
pi --provider soai --model YOUR_MODEL_ID --print 'Explain what this project does.'

Match contextWindow, maxTokens, reasoning, and input modalities to the selected model rather than copying optimistic values. The official Pi documentation linked below describes these fields.

Select SoAI in Pi's interface

  1. Start pi after saving models.json.
  2. Enter /model, or press Ctrl+L, to open the model selector.
  3. Choose provider soai and model YOUR_MODEL_ID, then send a short prompt.

Pi's picker can select a custom provider after it exists in models.json, but it does not create the provider or base URL. Use --provider and --model for headless selection.

MCP support and troubleshooting

Pi does not include an MCP client. Creating a SoAI MCP token does not make tools appear in Pi; use an MCP-capable client when SoAI tools are required.

Troubleshooting

If Pi cannot find the model, check the provider ID and the exact catalog model ID. For TLS errors, make the server CA available to Node.js with NODE_EXTRA_CA_CERTS. Do not disable certificate verification.

Related documentation