> 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/how-to-use-smart-router.md).

# How to use Smart Router

Smart Router automatically selects a suitable model for each request, so you don't have to choose between models yourself. Point your tool at nexos.ai and set the model to `auto-code`. Smart Router handles the rest.

{% hint style="warning" %}
Smart Router is currently optimized for coding work. You can send other types of requests, such as general writing, research, or data analysis, but the model selection may not be optimal for them. Support for more use cases is coming.
{% endhint %}

{% hint style="info" %}
Smart Router is a model choice, not a separate integration. If your coding tool already works with nexos.ai, you only need to change the model name.
{% endhint %}

### When to use Smart Router

#### Best suited for:

* **Coding agents and assistants**: Claude Code (CLI, Desktop App, Extension), Codex, Cursor, Pi Agent, OpenWork
* **Everyday development:** implementing features, refactoring, debugging, writing tests, explaining code
* **Long agent sessions** where tasks range from simple to complex

#### Not recommended yet:

* Chat that isn't about coding, content writing, or apps used by customers
* Workloads that need the same model every time, such as evaluations, regulated outputs, or fixed prompts in production
* Image, audio, or other tasks that aren't text

### Why use Smart Router for development

* **Lower cost on routine steps:** reading files, small edits, and summaries go to faster, cheaper models.
* **Stronger models for hard problems:** complex reasoning, refactoring, and debugging go to more capable models.
* **Less model management:** your configuration stays the same as routing improves.
* **One setting across coding tools:** the same model ID works in all supported tools.

### How it works

{% stepper %}
{% step %}
Your tool sends a request to `https://api.nexos.ai` with the model `auto-code`.
{% endstep %}

{% step %}
Smart Router analyzes the request.
{% endstep %}

{% step %}
Smart Router forwards the request to the chosen model and streams the response back in the format your tool expects (Anthropic or OpenAI).
{% endstep %}

{% step %}
Usage is logged in your nexos.ai Gateway platform, including the model that was actually used.
{% endstep %}
{% endstepper %}

### Model IDs

Smart Router uses the following model IDs:

| Model ID        | When to use                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `auto-code`     | Default                                                                                        |
| `auto-code[1m]` | Use with Claude Code. The `[1m]` parameter tells Claude Code to use a 1M token context window. |

### Set up your tool

Each integration guide has a **Smart Router** section with ready-to-paste configuration.

| Tool                                | What to change                                    | Guide                                                                             |
| ----------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------- |
| Claude Code (CLI and IDE extension) | `ANTHROPIC_MODEL` and the default model variables | [Claude Code](https://docs.nexos.ai/gateway-api/integrations/claude-code.md)      |
| Claude Code on Desktop app          | Custom model settings (developer mode)            | [Claude Desktop](https://docs.nexos.ai/gateway-api/integrations/claude-cowork.md) |
| Codex CLI                           | `model` in `config.toml`                          | [Codex CLI](https://docs.nexos.ai/gateway-api/integrations/codex-cli.md)          |
| Cursor                              | Custom model with the nexos.ai base URL           | Cursor                                                                            |
| Pi Agent (pi.dev)                   | Model in the provider config                      | [Pi Agent](https://docs.nexos.ai/gateway-api/integrations/pi-agent.md)            |

{% hint style="info" %}
Smart Router is tested with the tools listed above. Other coding tools that support a custom Anthropic-compatible or OpenAI-compatible base URL may also work.&#x20;

Contact us if you have questions about other tools.
{% endhint %}

### Quick test with the API

Before you configure a tool, check that your key and Smart Router work.

{% tabs %}
{% tab title="Anthropic Messages" %}

```shellscript
curl https://api.nexos.ai/v1/messages \
  -H "Authorization: Bearer $NEXOS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "auto-code",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Write a Python function that reverses a string"}]
  }'
```

{% endtab %}

{% tab title="OpenAI Chat Completions" %}

```shellscript
curl https://api.nexos.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEXOS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "auto-code",
    "messages": [{"role": "user", "content": "Write a Python function that reverses a string"}]
  }'
```

{% endtab %}

{% tab title="OpenAI Responses" %}

```shellscript
curl https://api.nexos.ai/v1/responses \
  -H "Authorization: Bearer $NEXOS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "auto-code",
    "input": "Write a Python function that reverses a string"
  }'
```

{% endtab %}
{% endtabs %}

| **Endpoint**         | **Used by**                                    |
| -------------------- | ---------------------------------------------- |
| /v1/messages         | Claude Code, Claude Desktop                    |
| /v1/chat/completions | Cursor, Pi Agent, most OpenAI-compatible tools |
| /v1/responses        | Codex CLI, OpenAI Agents SDK                   |

### Recommended settings

These settings apply to all tools. Each guide shows how to set them in that tool.

| Setting                                                                 | Why                                                                                 |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Send all model slots (main, fast or "haiku", subagent) to `auto-code`   | Otherwise some requests skip Smart Router                                           |
| Prompt cache TTL of 1h (Claude Code: `CLAUDE_CODE_PROMPT_CACHE_TTL=1h`) | Cheaper long sessions. Applies only when the request is routed to Anthropic models. |
| Turn off telemetry and other non-essential traffic                      | Stops requests from going to the vendor directly instead of through nexos.ai        |

{% hint style="info" %}
In shell examples, wrap `auto-code[1m]` in quotes, for example `export ANTHROPIC_MODEL="auto-code[1m]"`. Without quotes, zsh can fail with "no matches found
{% endhint %}

### See which models were used

The API response includes the model and token usage. Costs shown there may be wrong, because tools often calculate them using their own pricing.

To see requests, cost, and the model chosen for each request, open Gateway metrics in the nexos.ai Gateway platform. [See Usage](https://workspace.nexos.ai/gateway/metrics).

### How to enable

An AI Gateway platform owner must turn on Smart Router before anyone can use `auto-code`.

{% stepper %}
{% step %}
In nexos.ai, go to **Gateway management → Smart Router**.
{% endstep %}

{% step %}
Next to **Status**, click **Turn on**.
{% endstep %}
{% endstepper %}

By default, Smart Router picks models and default models from your company models.

{% hint style="info" %}
With the default setup, nexos.ai enables the models Smart Router needs automatically. To control which models it uses, turn on Advanced setup.
{% endhint %}

### Advanced setup (optional)

Use Advanced setup to choose exactly which models Smart Router can route to.

{% stepper %}
{% step %}
On the Smart Router page, turn on **Advanced setup**.
{% endstep %}

{% step %}
**Choose models:** select the company models Smart Router can pick from. We recommend selecting all of them. Only models that Smart Router supports appear in this list.
{% endstep %}

{% step %}
**Choose default models:** pick a default model for each request type. Smart Router uses the default when it can't tell which model fits a request. The suggested model is listed first.
{% endstep %}
{% endstepper %}

You can change these settings at any time. Each model's price per 1M input and output tokens appears in the model list.

{% hint style="info" %}
If you turn off Smart Router, requests that use `auto-code` will fail. Switch your tools to a specific model first.
{% endhint %}

### FAQ

**Can I use Smart Router outside of coding?**&#x20;

Yes, but it is tuned for development tasks today, so results and cost savings may vary. For other tasks, contact us and we will evaluate whether it works or make it work.

**Do tool calls, images, and long context work?**&#x20;

Yes.

**My tool shows the wrong model name.**&#x20;

The tool sees only `auto-code` in the request. The response contains the exact name of the model that answered. You can also check Smart Router metrics in the nexos.ai Gateway platform to see the model used.

**My tool shows the wrong costs.**&#x20;

Tools often calculate costs using their own known pricing, which can be misleading for `auto-code`. Check Smart Router usage in the nexos.ai Gateway platform to see the actual costs.

**My tool shows the wrong context size.**&#x20;

Many tools recognize that `auto-code` supports a 1M context window. Claude Code needs the model name `auto-code[1m]` to use it. If a tool still has problems, contact us.

**I get "model not found" for `auto-code`.**&#x20;

Ask your nexos.ai Gateway platform owner to turn on Smart Router in Gateway management.


---

# 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/how-to-use-smart-router.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.
