> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/gateway-api/integrations/pi-agent.md).

# Pi Agent Integration

A step-by-step guide to connecting Pi Agent to the nexos.ai API Gateway, from installing Pi to configuring models.json and selecting your model.

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 <a href="#how-to-connect-pi-agent-with-nexos.ai" id="how-to-connect-pi-agent-with-nexos.ai"></a>

{% stepper %}
{% step %}

### Install Pi Agent

Install Pi using the recommended installation script:

{% code lineNumbers="true" %}

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

{% endcode %}

Confirm that Pi is installed:

{% code lineNumbers="true" %}

```
pi --version
```

{% endcode %}
{% endstep %}

{% step %}

### Configure your nexos.ai API key

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

{% code lineNumbers="true" %}

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

{% endcode %}

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

For Zsh:

{% code lineNumbers="true" %}

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

{% endcode %}

For Bash:

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% step %}

### Configure nexos.ai as a provider

Pi loads custom providers and models from:

{% code lineNumbers="true" %}

```
~/.pi/agent/models.json
```

{% endcode %}

Create the configuration directory if it does not already exist:

{% code lineNumbers="true" %}

```
mkdir -p ~/.pi/agent
```

{% endcode %}

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

<pre class="language-json" data-line-numbers><code class="lang-json">{ 
  "providers": { 
<strong>    "nexos": { 
</strong>     "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" 
        } 
      ] 
    } 
  } 
}
</code></pre>

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.

{% hint style="warning" %}
**Note:** If \~/.pi/agent/models.json already contains other providers, add the nexos provider to the existing providers object rather than replacing the file.
{% endhint %}
{% endstep %}

{% step %}

### 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:

{% code lineNumbers="true" %}

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

{% endcode %}

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:

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

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:

{% code lineNumbers="true" %}

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

{% endcode %}

The nexos.ai Models endpoint returns information such as context\_length, max\_tokens which can help you configure these values correctly.

{% hint style="info" %}
**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.
{% endhint %}
{% endstep %}

{% step %}

### Verify the configuration

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

{% code lineNumbers="true" %}

```
pi --list-models
```

{% endcode %}

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

{% code lineNumbers="true" %}

```
pi --list-models nexos
```

{% endcode %}

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

If they are listed, the integration is ready to use.
{% endstep %}

{% step %}

### Start Pi with nexos.ai

Start Pi normally:

{% code lineNumbers="true" %}

```
pi
```

{% endcode %}

Then use the model selector:

{% code lineNumbers="true" %}

```
/model
```

{% endcode %}

Choose one of the models configured under the nexos provider.

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

{% code lineNumbers="true" %}

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

{% endcode %}

Alternatively, use the provider/model format:

{% code lineNumbers="true" %}

```
pi --model "nexos/GPT 5.6 Sol"
```

{% endcode %}

Pi will now route requests for the selected model through the **nexos.ai API Gateway**.
{% endstep %}
{% endstepper %}

## Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

### nexos.ai models are not listed <a href="#nexos.ai-models-are-not-listed" id="nexos.ai-models-are-not-listed"></a>

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

{% code lineNumbers="true" %}

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

{% endcode %}

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:

{% code lineNumbers="true" %}

```
pi --list-models nexos
```

{% endcode %}

### A model is not found <a href="#a-model-is-not-found" id="a-model-is-not-found"></a>

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

{% code lineNumbers="true" %}

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

{% endcode %}

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 <a href="#a-model-is-listed-but-requests-fail" id="a-model-is-listed-but-requests-fail"></a>

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nexos.ai/gateway-api/integrations/pi-agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.