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:
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.
{
"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.
{
"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.
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:
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
primexprovider ID, the exact model ID and a resolvable API key. Opening/modelreloadsmodels.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.