Smart Routes

Stop sending every task to the same model. Smart Routes choose the right configured model for each request while your applications keep using one stable model name.

Reserve premium models for work that benefits from them. Send routine requests to faster, less expensive, or local models. Change the policy in Nexus without reconfiguring every connected tool.

Clients address a Smart Route as:

@route/<slug>

Free includes two active Smart Routes. Pro includes unlimited active Smart Routes. Enterprise accounts use their assigned limit.

One model name, better decisions behind it

A Smart Route combines:

• A stable name that applications can keep using
• A reliable fallback target
• Optional routing choices, called lanes, for different kinds of work
• An optional image fallback for multimodal requests
• Data Protection behavior for every path

When a request arrives, Nexus selects a matching lane or uses the fallback. A route can target a direct model or a Smart Balancer pool, allowing routing policy to choose the type of model and the balancer to choose the healthiest destination.

Prepare routing

Smart routing uses a small local classifier so routing decisions do not require sending the request to another online service.

1. Open Smart Routes.
2. Select Prepare router.
3. Choose a compatible local runtime such as MLX, llama.cpp, or Ollama.
4. Let Nexus install or configure the routing model when supported.
5. Keep a valid fallback model available while preparation completes.

If the router is unavailable, Nexus uses the configured fallback rather than leaving applications without a target.

Create a Smart Route

Start from a curated route or build one from a blank configuration:

1. Give the Smart Route a recognizable name and stable slug.
2. Set the default fallback.
3. Add a routing choice for each kind of work that should use a different target.
4. Write a clear When to use it description for every choice.
5. Assign a model or Smart Balancer pool to each choice.
6. Review Data Protection for every possible path.
7. Test representative prompts, then validate and enable the route.
8. Use its @route/<slug> value as the application's model name.

A strong first route is intentionally small: one dependable fallback and one or two meaningful lanes. Add complexity only when live traffic shows a clear reason.

What the description controls

The application chooses the Smart Route by sending @route/<slug> as the model. Once the request enters that Smart Route, Nexus compares the request with each routing choice's name and When to use it description.

That description is the main explanation of what belongs in the lane. It directly influences whether the local router selects that choice or sends the request to another choice or the fallback.

The slug does not influence classification. Choose it for stability and readability, not as a routing instruction.

Write descriptions around the requested action

Describe what the user is asking Nexus to do—not simply the subject matter in the message and not the strengths of the target model.

A useful description usually includes:

• The primary action, such as writing, debugging, summarizing, translating, analyzing, or extracting
• A few closely related examples that belong together
• A boundary when another lane could look similar
• Concrete language that differs clearly from the other choices

For example:

Avoid descriptions such as:

• “Use the best model”
• “Hard questions”
• “General requests”
• “Anything about technology”
• Several choices that all say “analysis,” “complex work,” or “high quality”

Those descriptions either provide too little routing signal or overlap so heavily that the router cannot choose reliably.

Intent matters more than payload

Nexus tries to classify the overall action in the user's request. Pasted code, documents, quotations, headings, and examples are treated as material the user may be asking the model to work on—not automatically as the task itself.

• “Summarize this SQL migration” should match a summarization choice, not a coding choice.
• “Translate this error message into Spanish” should match translation, even though the payload discusses an error.
• “Fix the bug in this function” should match coding because changing the code is the requested action.

Write descriptions that make these boundaries obvious.

Use the fallback deliberately

The default fallback handles requests when:

• No routing choice clearly matches
• The router cannot classify the request
• The selected choice cannot use its configured target
• The request type needs a compatible endpoint-specific fallback

Choose a dependable general-purpose fallback. Do not create a catch-all lane that duplicates it; broad lanes make narrower descriptions harder to distinguish.

Test before enabling

Use Try a prompt in the Prompt lab to preview where a request would go. A preview asks the router only: it does not call the destination model or save the prompt.

Test at least:

1. An obvious example for every routing choice.
2. A near-boundary example that could match two choices.
3. A request that should use the fallback.
4. A request containing pasted content from another category.

If prompts land in the wrong choice, sharpen the descriptions before changing models. Validation confirms that the configuration and targets are usable; prompt testing confirms that the routing language describes the work accurately.

Understand every decision

The Smart Routes workspace separates live operation from longer-term evaluation:

• Live shows request rate, lane selections, fallbacks, and recent routing activity.
• Insights compares routed traffic with fallback behavior using quality, latency, and cost evidence when enough data exists.
• Routes manages route targets, lanes, protection behavior, and enabled state.

Request history records the information needed to explain routing decisions without storing prompt or response text.

Keep conversations coherent

Nexus derives conversation identity from supported request shapes and tries to keep related turns on a useful target. This can preserve warm prompt caches and avoid repeatedly processing a stable prefix on another destination.

When the work changes substantially, Nexus may choose a better lane instead of preserving affinity at the expense of quality or availability.

Protect sensitive data before it leaves

For each protected lane and fallback, decide whether Nexus should:

• Send a cleaned request
• Block the request
• Send it through a designated sensitive-data route

You also choose what happens when the protection check cannot run. Sending the original request can expose sensitive content, so allow that behavior only when the destination and workflow permit it.

Read Security before routing protected data to online providers or remote machines.

Limits and downgrades

Free can execute two active Smart Routes. Nexus blocks creation or activation of a third active route at the Runtime API boundary.

If an account moves to a lower limit, Nexus keeps the extra route configuration but prevents it from executing. Routes, credentials, models, and usage history are not deleted.