AI providers and routing

Your Jootle instance does not run a language model itself. It connects to one (or more) AI providers, and every conversation, task, and automation flows through whichever provider you’ve connected.

You’ll find this in your sidebar under System → AI Configuration.

If you only ever connect one provider and leave it as Primary, you can skip the rest of this chapter. The defaults are fine. The rest of this chapter is for customers who want to use a cheaper provider for everyday chat and a stronger one for the work that needs it, or who want a vision-capable provider only for images, or who want a backup that takes over when the main one is down.

The two ways to connect

When you set up your instance, you chose one of these:

Sign in with Claude. You connected your Anthropic account (Claude Pro, Max, or Team). Your assistant uses your Claude subscription to do its work. You don’t get a separate bill from Anthropic for usage; it draws from the limits that come with your subscription.

API key. You pasted an API key from a provider (Anthropic, OpenAI, Google Gemini, DeepSeek, and more). Your assistant uses that key, and the provider bills you directly for what you use. This is called BYOK, “bring your own key”.

You can switch between these later, and you can have multiple connections at once. Only one is marked Primary at any time.

What “Primary” means

The Primary provider handles your assistant’s default work: ordinary chat, quick analyses, anything that hasn’t been routed somewhere else.

If you want a single provider to handle everything, just connect it and mark it Primary. Done.

If you want different providers for different kinds of work, keep reading.

Connecting more than one provider

Click Add provider on the AI Configuration page and connect a second one. You’ll fill in the same fields (provider type, API key, default model). The new one shows up alongside your existing connections and starts in a non-Primary state.

A reason you might do this:

Cost. A provider like DeepSeek is dramatically cheaper than Claude for everyday conversation, so you make DeepSeek Primary and use Claude only for the work that needs it.
Vision. You want a provider with strong image understanding (Gemini is good at this) for image-heavy tasks, and Claude or another provider for text.
Reliability. You want a backup that automatically takes over when your main one is having a bad day.

You can have several. There’s no hard limit.

Claude model selection

If your Primary is Claude, you’ll see a section called Claude Model Selection. Claude has several model sizes, and they cost different amounts and have different strengths.

Tier	Use it for
Haiku	Short, simple replies. Quick classifications. Cheap and fast.
Sonnet	The default for most conversation and tasks. Strong all-rounder.
Opus	The hardest reasoning, the most complex multi-step work. Slowest and most expensive.

Your assistant picks a tier automatically based on the complexity of what’s being asked. You can override that, for example, force everything to Sonnet, or use Opus only for tasks and Haiku for short replies, but the defaults work well, and most customers leave this alone.

This section appears only when your Primary is Claude. Other providers have their own model selection in the provider’s edit dialog.

Advanced: routing rules

This is the section that lets you say “for this kind of work, use this specific provider, even if it isn’t Primary.”

Most customers don’t need this. If your AI is working well, leave routing rules alone.

Here’s the mental model. Inside your assistant there are specialist agents, each one good at a specific kind of work. There’s a vision agent that looks at images. There’s a builder agent that writes code. There’s a research agent that does web work. When a task fires, your assistant picks the agent best suited to it, then runs the work through whichever AI provider is configured for that agent.

By default, every agent uses the Primary. Routing rules let you override that per agent.

Setting up a rule

On the AI Configuration page, scroll to Advanced: Routing Rules and click Add rule. You’ll pick:

Context. Either default (a fallback for any task that doesn’t match a more specific rule) or agent:<agent_name> (override for a specific agent).
Backend. Which connected provider should handle work matching this context.
Priority. Lower numbers win when multiple rules match. A rule with priority 0 beats a rule with priority 5.

A common configuration. If your Primary is DeepSeek (cheap, good at chat) but you want Claude for the harder coding and structured work:

Context	Backend	Priority
`agent:builder`	claude	0
`agent:planner`	claude	0
`default`	deepseek	0

With those rules, casual chat goes through DeepSeek (your Primary). Tasks assigned to the builder or planner agent run on Claude. Everything else on the default fallback (also DeepSeek here).

How rules are resolved

For each task, your assistant looks for a rule in this order:

A rule for that specific agent (agent:<name>).
A rule for the default context.
The Primary provider, if no rules match.

The first healthy backend that matches wins. If a backend is unhealthy (out of credits, expired key, provider down), your assistant skips it and falls through to the next match.

What today’s routing does and doesn’t cover

Be honest about the limits.

Routing applies to tasks, the work your assistant runs in the background, research jobs, multi-step playbooks, agent assignments. These flow through the routing rules.

Routing does not yet apply to chat, the messages you exchange with your assistant in the chat window. Those always use the Primary, no matter what your rules say. So if you set DeepSeek as Primary and Claude as a per-agent override, asking “what’s on my calendar today?” in chat hits DeepSeek. Asking your assistant to run a task that ends up assigned to a Claude-routed agent hits Claude.

Routing is explicit, not capability-aware. You assign agents to backends by name. There’s no “this call needs vision, automatically pick a vision-capable provider”. If a backend can’t handle what’s asked of it, it’ll say so, and you’ll see it in the response.

No automatic retry on a stronger model. If a cheaper provider gives a poor answer (some models are less reliable at following structured-output instructions), your assistant doesn’t currently re-run the same prompt on a stronger model. You’d need to ask again, or move that kind of work to a stronger backend with a routing rule.

We’re improving these. The current shape is enough to do useful multi-provider work, but it isn’t doing the smart picking automatically yet.

Health, status, and disconnects

Each connected provider shows a health dot.

Green: recently used and responding cleanly.
Yellow: used recently but had at least one failure. Often transient.
Red: failing repeatedly. Your assistant is skipping it and routing around it.

If a provider goes red:

Click into it. The error is usually shown.
Common causes: API key expired or revoked, account out of credits, the provider’s API is down.
Fix the underlying issue (rotate the key, top up credits, wait for the provider to recover).
Click Test connection to verify and the dot will go back to green.

You can disconnect a provider any time. Your routing rules pointing to it will stop matching, and work will fall through to the next rule or the Primary.

A few practical recipes

”Cheapest option that still works”

Primary: DeepSeek or another low-cost provider.
One routing rule: agent:builder → claude (or whatever stronger backend you have).
Leave the rest on Primary.

You’ll spend most of your token budget on the cheap provider for everyday chat, and only burn the expensive one when the builder agent fires.

”Vision specialist plus my main one”

Primary: your usual provider (Claude, OpenAI, whichever you prefer).
Add Gemini as a second provider.
Routing rule: agent:vision_agent → gemini.

Vision-related tasks get sent to Gemini. Everything else stays on your Primary.

”Fallback for outages”

Primary: your usual provider.
Add a second provider you’d be okay using as a backup.
No rules needed: when the Primary goes red, your assistant won’t have anywhere to route work, and tasks will pause. (We’re improving automatic fallback for the next release.)

Where this is heading

Two things we’re planning to add post-launch:

Capability-aware routing. Your assistant will know what each provider is good at and pick automatically when no explicit rule applies. You’ll set tiers (“cheap chat”, “strong task”, “vision”) instead of writing rules per agent.
Auto-escalation. When a cheaper provider gives a bad answer (empty output, malformed structured data), your assistant will retry once on a stronger model and learn from the failure so it doesn’t repeat.

If you’re already comfortable with the per-agent rule approach, you’ll be able to keep using it. The new behavior will sit on top.

Quick reference

One provider connected: simplest. Primary handles everything. No rules needed.
Multiple providers, no rules: only the Primary is used. The others are connected but idle.
Multiple providers with rules: tasks route by agent. Chat still uses Primary.
Health dots tell you which backends are working. Red ones get skipped.
Disconnecting a provider is safe; rules pointing to it just stop matching.