Skip to main content

Connect Pi

Use Primex as a custom provider for the Pi coding agent. This guide uses openai-completions, Pi's Chat Completions adapter. Choose an eligible model in Pi Setup.

Install and configure​

The reviewed release is Pi 1.4.0, requiring Node.js 22.19.0 or newer. For the matching npm installation:

Shell
npm install -g @earendil-works/pi-coding-agent@1.4.0
export PRIMEX_API_KEY=YOUR_API_KEY

Merge this provider into ~/.pi/agent/models.json. Replace the model placeholder with your exact Primex offering ID; keep other providers.

JSON
{
"providers": {
"primex": {
"baseUrl": "https://gateway.primexos.com/v1",
"apiKey": "${PRIMEX_API_KEY}",
"api": "openai-completions",
"authHeader": true,
"models": [
{ "id": "YOUR_LIVE_CHAT_MODEL", "name": "Primex model" }
]
}
}
}

Merge the following settings into a separate file, ~/.pi/agent/settings.json. They set a 60-second provider request deadline and disable agent and provider automatic retries for the first test. Preserve unrelated settings.

JSON
{
"retry": {
"enabled": false,
"provider": { "timeoutMs": 60000, "maxRetries": 0 }
}
}

PI_CODING_AGENT_DIR can change the agent directory. Project .pi/settings.json can override user settings; the first-test commands below ignore trusted project configuration with --no-approve.

Pi resolves ${PRIMEX_API_KEY} from the environment of the process that starts it. Existing stored credentials or a command-line key can take precedence over this value. Keep secrets out of prompts, committed configuration and command history. See Pi's model configuration and settings reference.

Setup includes contextWindow and maxTokens only when Catalog publishes positive limits. Pi otherwise uses generic defaults, which are not evidence of the selected model's capacity. Confirm missing limits before long tasks. The configuration starts with text input and no advertised thinking mode; image inputs, reasoning options, compaction and auxiliary models need separate checks.

Send a first request​

Use a disposable directory and replace YOUR_LIVE_CHAT_MODEL below. This command runs once without session persistence or tools and disables extensions, skills and prompt templates for the initial test.

Shell
pi --provider primex --model YOUR_LIVE_CHAT_MODEL --print --no-session --no-tools --no-extensions --no-skills --no-prompt-templates --no-approve "Hello from Primex"

Expect a text reply in the terminal. The client uses streaming Chat Completions even though print mode displays the final answer. Check the exact model and API key in Usage before sending another request.

Pi's local cost display can use generic or zero custom-model prices. Primex Usage is the record of actual account charges. A failed or timed-out client request does not establish whether the provider already processed it; inspect Usage before retrying. The 60-second deadline is intended for this short test, not lengthy agent work.

Verify a harmless tool turn​

Create a harmless README.md in the disposable directory, then run:

Shell
pi --provider primex --model YOUR_LIVE_CHAT_MODEL --print --no-session --tools read --no-extensions --no-skills --no-prompt-templates --no-approve "Read README.md and report its first heading."

Check that Pi calls read, returns the file content to the model, and gives the correct heading. Verify both requests in Usage. The command enables only the read tool and disables extensions, including built-in MCP support. --tools read alone does not remove MCP access in a normal extended session. This command is not an operating-system sandbox; use a directory without sensitive files.

After these checks, interactive pi --provider primex --model YOUR_LIVE_CHAT_MODEL uses your normal local configuration and tool policy. Review project trust, extensions and tool access before enabling them.

Common fixes​

  • Model missing: confirm valid JSON, the primex provider ID, the exact model ID and a resolvable API key. Opening /model reloads models.json.
  • 401: check the launching process's key, credential precedence and Bearer authentication. Do not print credentials into a shared log.
  • 402, 429 or server errors: inspect balance, key caps, Usage and the error guide. Retry deliberately after resolving the cause.
  • Unexpected repeated requests: check both retry settings and project overrides. A successful tool turn normally has a request before and after the tool result; compaction and extensions can add other requests.
  • Context or tool errors: use the model's current published limits and verify the exact tool schema. Chat Completions eligibility alone does not qualify every agent feature.

Remove the configuration​

Remove only providers.primex from models.json, review any saved default model, and restore retry settings if they were changed for this test. Remove a separately stored Primex credential if you created one, and revoke the dedicated key in API Keys when it is no longer needed.

Need help connecting? Report a setup issue.