Pi Agent Integration

Connect Pi Agent to the nexos.ai API Gateway to use models available in your nexos.ai platform directly from the terminal.

Pi supports custom OpenAI-compatible providers through its models.json configuration. By adding nexos.ai as a provider, Pi can route model requests through the Gateway using your nexos.ai API key.

How to connect Pi Agent with nexos.ai

Install Pi Agent

Install Pi using the recommended installation script:

curl -fsSL https://pi.dev/install.sh | sh

Confirm that Pi is installed:

pi --version

Configure your nexos.ai API key

Export your nexos.ai API key as an environment variable:

export NEXOS_API_KEY="your-team-api-key-here"

To make the API key available in future terminal sessions, add the same line to your shell profile.

For Zsh:

echo 'export NEXOS_API_KEY="your-team-api-key-here"' >> ~/.zshrc 
source ~/.zshrc

For Bash:

echo 'export NEXOS_API_KEY="your-team-api-key-here"' >> ~/.bashrc 
source ~/.bashrc

Important: Keep your API key secure. Do not commit it to source control or store it directly in models.json.

Configure nexos.ai as a provider

Pi loads custom providers and models from:

~/.pi/agent/models.json

Create the configuration directory if it does not already exist:

mkdir -p ~/.pi/agent

Create or update ~/.pi/agent/models.json with the nexos.ai provider configuration:

{ 
  "providers": { 
    "nexos": { 
     "baseUrl": "https://api.nexos.ai/v1", 
     "apiKey": "$NEXOS_API_KEY", 
     "authHeader": true, 
     "api": "openai-completions", 
     "models": [ 
        { 
           "id": "GPT 5.6 Sol" 
        }, 
        { 
           "id": "Claude Sonnet 5" 
        } 
      ] 
    } 
  } 
}

This configuration tells Pi to:

Route requests through https://api.nexos.ai/v1.
Read the API key from the NEXOS_API_KEY environment variable.
Send the API key using the Authorization: Bearer header.
Use Pi’s OpenAI-compatible Chat Completions adapter.
Make the models defined in the models array available in Pi.

Note: If ~/.pi/agent/models.json already contains other providers, add the nexos provider to the existing providers object rather than replacing the file.

Choose your models

The models in the example above are only examples. You are not limited to GPT 5.6 Sol or Claude Sonnet 5.

You can add any model available to your nexos.ai workspace by including its model ID in the models array.

To see the models available to your API key, query the nexos.ai Models endpoint:

curl "https://api.nexos.ai/v1/models" \ 
-H "Authorization: Bearer $NEXOS_API_KEY"

The response contains the models currently available to your account. Copy the model’s id and add it to ~/.pi/agent/models.json.

A minimal model entry only requires an id:

{ 
   "id": "<model-id-from-nexos>" 
}

For example, you can configure several nexos.ai models:

"models": [ 
  { 
      "id": "<model-id-1>" 
  }, 
  { 
      "id": "<model-id-2>" 
  }, 
  { 
      "id": "<model-id-3>" 
  } 
]

You can also provide additional model metadata when needed:

contextWindow — the model’s context window in tokens.
maxTokens — the maximum number of output tokens.
reasoning — whether the model supports reasoning controls in Pi.

For example:

{ 
    "id": "GPT 5.6 Sol", 
    "maxTokens": 128000, 
    "contextWindow": 922000, 
    "reasoning": true 
}

The nexos.ai Models endpoint returns information such as context_length, max_tokens which can help you configure these values correctly.

Tip: Treat GET /v1/models as the source of truth for the models available to your nexos.ai API key. Because this setup uses Pi’s openai-completions adapter, the selected model should support the chat_completion endpoint.

Verify the configuration

After saving models.json, confirm that Pi can see the nexos.ai models:

pi --list-models

You can also filter the output to show only nexos.ai models:

pi --list-models nexos

The models you added to models.json should appear under the nexos provider.

If they are listed, the integration is ready to use.

Start Pi with nexos.ai

Start Pi normally:

pi

Then use the model selector:

/model

Choose one of the models configured under the nexos provider.

You can also start Pi with a specific nexos.ai model directly:

pi --provider nexos --model "GPT 5.6 Sol"

Alternatively, use the provider/model format:

pi --model "nexos/GPT 5.6 Sol"

Pi will now route requests for the selected model through the nexos.ai API Gateway.

Troubleshooting

nexos.ai models are not listed

First, confirm that the API key is available in your current shell:

test -n "$NEXOS_API_KEY" && echo "NEXOS_API_KEY is set"

Then check that:

~/.pi/agent/models.json contains valid JSON.
The provider is configured as nexos.
Each model is included in the models array and has an id.
NEXOS_API_KEY is available in the shell where Pi is running.

After making any changes, run:

pi --list-models nexos

A model is not found

Retrieve the models available to your nexos.ai API key:

curl "https://api.nexos.ai/v1/models" \ 
-H "Authorization: Bearer $NEXOS_API_KEY"

Copy the model’s id exactly as returned and add it to the models array in ~/.pi/agent/models.json.

A model is listed but requests fail

Check the model’s endpoints field in the response from GET /v1/models.

This configuration uses Pi’s openai-completions adapter, which sends requests through the Chat Completions API. Make sure the selected model includes chat_completion in its supported endpoints.

PreviousZoo Code

Nextn8n

Last updated 6 days ago