Models
10 min read
Kujira can run your agents' reasoning through a cloud provider or with Ollama in your own infrastructure. This section brings together the available options, how to configure them, and how to assign them to each agent.
Choose where the model runs
| Option | When to choose it | What you need to configure |
|---|---|---|
| Cloud provider | You want to start quickly and delegate infrastructure to a provider. | The provider credential and the model each agent will use. |
| OpenRouter | You want to try or combine models from several providers with a single key and a single balance. | An OpenRouter key and the model each connection will carry. |
| Ollama | You need processing to run on a machine you control. | An Ollama instance reachable from the agent container and a downloaded model. |
A provider's connections
Go to Settings > Models and open the provider you want to use. Every provider has a list of connections and they all work the same way: a connection is one specific account or one specific machine, with its own name and credential.
- You can have several connections to the same provider. The team subscription and an API key billed separately are two Claude connections, not a duplicate. The same goes for one Ollama per machine.
- The name is required. It is the only thing that tells one connection from another, both in this list and in each agent's configuration. Say which account or which machine it is: “Team subscription”, “Billing key”, “Laptop Ollama”.
- Each connection can be turned on or off, edited or removed, and one of them is the provider's default.
Add a connection
Open the provider
In Settings > Models, select the provider in the sidebar. You will see its list of connections and, next to the title, how many there are.
Select “Add connection”
The form opens. You need permission to edit organization models.
Name it and choose the type
The name is required. The type—Subscription or API key—decides which address the connection points at and how it authenticates, so it is chosen at creation and not changed afterwards: to move from one option to the other, add another connection.
Add the credential and save
Paste the provider key. With Claude you can also authorize the subscription in the browser without pasting anything. If the connection is a machine (Ollama), this is also where you enter its address, model, and context window. With OpenRouter you enter the model, and the context window if you pin a specific one.
The default connection
The default is the one used by agents that have not picked a specific connection. There is one per provider, marked on its row.
- The first connection you add to a provider is marked automatically.
- To change it, use Make default on the row you want. It must be turned on and hold a credential: a connection that is off or empty cannot start anything.
- If you turn off or remove the default, Kujira promotes another connection of the same provider that can start agents. If none is left, the provider has no default and its inheriting agents will not start until you choose one.
Remove a connection
If agents start with that connection, Kujira does not simply remove it: it tells you how many they are and asks which other connection they move to. Pick the destination under Move the agents to and confirm with Move and remove; those agents restart to boot with the new connection.
If you would rather keep it—to use it again later, for example—turn it off instead of removing it.
Model credential and tool credential
A model credential lets an agent use its AI provider. Keys for a CRM, API, or integration are managed separately in Credentials.
Check a connection
Under each connection's name there is a Test button. It checks the credential, the address it points at and —when the connection carries its own model— that the model exists at the provider, all at once, without waiting for an agent to fail on its first turn.
The check uses no tokens: Kujira asks for the provider's model catalogue or a token count, and never sends a conversation.
| Result | What it means |
|---|---|
| It works | The credential is valid and the address answers. |
| The provider rejects the credential | The key is no longer valid: revoked, expired, or belonging to another account. Replace it and test again. |
| The address cannot be reached | Nothing answers there. Check that it is spelled right and reachable from wherever the check runs. |
| The model is not at the provider | The credential works, but the model the connection names is not in its catalogue. The agent would not start. |
| The provider is throttling requests | That is on their side, not yours. Wait a moment and test again. |
You need the same permissions as to change the credential, and every check is recorded in the Activity log. If you test twice in a row, the button tells you how many seconds are left: each press is a call to the provider.
When the check runs from your own server
Kujira only calls addresses on the internet. These connections do not fit there, so the check is run by the supervisor on your server instead of by the panel:
- Ollama, and any connection declared as being on a private network. That address is yours, and Kujira never calls it from outside.
- A Claude subscription. Its authorization is only ever used from your own server, the same as when you connect or remove it.
The button is the same and sits in the same place. The difference is that it needs one of your servers running: if none is, the check says so instead of talking to you about the credential.
If you have several servers, you pick which one tests from. That is not a detail: a connection is not tied to a server, and an address like host.docker.internal means a different machine on each one. The dropdown appears next to the button when there is more than one.
| Result | What it means |
|---|---|
| None of your servers is connected | The check runs from your server and none is up. Start it and test again. |
| The supervisor on that server is older than this check | Update it by running sudo kujira update on that server, then test again. See Updating the supervisor. |
Checking a local engine
When you test an Ollama connection, Kujira also tells you which models that machine has downloaded, plus the two context window figures:
- Model window — the most that model supports.
- Window served — what your server is actually serving.
When the second is smaller than the first, the check comes back amber: the connection works, but long conversations will be cut off without warning once they reach that limit. Ollama serves 4,096 tokens by default; you raise it with OLLAMA_CONTEXT_LENGTH on the machine where it runs.
Kujira does not change that figure on its own. Promising the agent a window the engine does not serve does not fail at startup: it fails mid-conversation, which is much harder to diagnose.
If the model the connection names is not downloaded, the check says so and shows you the ones that are.
Testing is not switching on
A connection that is switched off can be tested too, which is the normal thing to do before switching it on. A successful test does not start it.
Setup guides
Claude
Connect a Pro or Max subscription, or create an Anthropic API key for pay-per-use billing.
Kimi
Configure a Kimi Code plan or pay-per-token key without mixing their credentials.
MiniMax
Use a Token Plan or API key and understand the difference between both options.
OpenRouter
Use models from many providers with a single key, or let OpenRouter pick the model for each request.
Ollama
Run local models on a machine in your infrastructure and connect them to Kujira.
Choose an agent's connection
In the agent's Configuration > Model, the Connection section comes before the model because it decides which models the agent can use: a Claude connection only serves Claude models. The dropdown offers:
| Option | What it means |
|---|---|
| Inherit from the organization | Uses the default connection of the provider that matches its model. If you change that default tomorrow, this agent changes with it. |
| An organization connection | Always boots with that one, by name, even if the organization changes its default. This is what you need when you have several connections to the same provider and want to separate spend or point at one particular machine. |
| An own connection | Listed under This agent only. It is an account only this agent can use: it does not appear in Settings > Models and no other agent inherits it. |
If the agent is running, saving a connection change restarts it on its own so it starts using the new one.
Choose by name, not by billing option
With several connections to the same provider, “Claude” does not say which one. That is why the dropdown shows names: the connection already carries its own billing option, address, and credential.
An agent's own connections
When an agent needs an account you do not share with the rest —someone's personal subscription, a test key—, click Own connections next to the dropdown. From there you can add, edit, turn off, and remove them with the same fields as in Settings > Models, except the default option: a connection only one agent uses cannot be the one the others inherit.
- Being able to edit the agent is enough. Setting a custom address, however, requires permission to edit the organization's models.
- For Claude, you can connect the subscription from the browser, just like in Settings > Models.
- You cannot remove the connection the agent boots with: pick another one in the dropdown first.
- Each agent can have up to ten.
Choose an agent model
Under Configuration > Model, let an agent inherit the default model or assign a specific one. The list only shows the models the chosen connection can serve. Changing the model requires restarting the agent.
| Option | When it is useful |
|---|---|
| Inherit | You want to apply a common organization policy. |
| Model family | You prefer to always use the newest recommended version in a family. |
| Specific version | You need stability for a flow you have already validated. |
If the agent is pinned to a connection that carries its own model—the Ollama and OpenRouter case—that model wins.
After changing the model, restart the agent before continuing. If you also change connection or provider, a restart is essential: the address and the credential are fixed when the container starts.
Shared or dedicated credential
By default, an agent uses one of its organization's connections. This is suitable in most cases: it centralizes billing and reduces duplicated configuration.
Assign a dedicated credential to an agent only when it must use a different account you do not want to share. To separate a customer's spend or isolate a test environment it is usually enough to add another connection to the organization and pin it to that agent, with no loose credentials to maintain.
A clear policy prevents surprises
If all agents share a provider and budget, keep one connection marked as default and leave agents on Inherit. Reserve exceptions for cases that genuinely need isolation.
Choose thoughtfully
Complex work
Prioritize a more capable model when an agent must analyze, plan, or make more nuanced decisions.
Repetitive tasks
Consider faster or more economical models for classification, summarization, or predictable flows.
Ollama
If you need the model to run in your own infrastructure, review the experimental Ollama integration.
Monitor usage
Cost and limits depend on the provider option and model you choose. Set limits at organization or agent level and review them regularly in Usage and limits.
The Statistics view analyzes each agent's usage in detail: filter by period, granularity, and channel, group data by agent, and review changes over time. It also separates input, output, and cache tokens to show what drives estimated spend.