Models

12 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.
Gemini	You have Google credit and want to use its models with an AI Studio key.	A Google AI Studio API key and the model for each agent.
OpenAI	You have OpenAI credit and want to use its models with an API key.	An OpenAI API key and the model for each agent.
Grok	You have an X plan or SuperGrok, or xAI credit, and want to use Grok models.	Your subscription or an xAI API key, and the model for each agent.
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.
vLLM	Your engine speaks the OpenAI API: vLLM, LM Studio, llama.cpp or SGLang.	The engine reachable from the agent container and the model it serves.

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 with a star in its header.

• The first connection you add to a provider is marked automatically.
• To change it, press the star of the one 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 which ones they are (only how many, for those you do not manage) and asks which other connection they move to. Under Move the agents to you pick, in a single dropdown, the destination connection —which can belong to another provider— and the model they will work with. Confirm with Move and remove: those agents use the new connection from their next reply, without restarting.

Conversations and channels that had it chosen, including other people's, switch to Auto and keep using their agent's connection. Kujira tells you how many there are before you confirm.

If you would rather keep it—to use it again later, for example—turn it off instead of removing it. Turning it off, or removing its key, leaves the agents that use it unable to reply until you turn it back on, give it a key or move them to another connection.

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, vLLM 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 window served is 64k or less, the check comes back red: that connection is no use for an agent, because the model is left with no room to work. That is what happens on a fresh Ollama install, which serves 4,096 tokens; you raise it with OLLAMA_CONTEXT_LENGTH on the machine where it runs.

When it serves more than 64k but less than the model supports, it comes back amber: the connection works, but long conversations will be cut off without warning once they reach that limit.

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.

Gemini

Connect Google models with an AI Studio key.

OpenAI

Connect OpenAI models with an API key.

Grok

Connect Grok models, by xAI, with your subscription or an API key.

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.

vLLM

Connect vLLM, LM Studio, llama.cpp, SGLang or any engine that speaks the OpenAI API.

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, it starts using the new connection from its next reply, without restarting.

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, choose the agent's model. Every agent needs one: without a model it is not created and does not start. The list only shows the models the chosen connection can serve. The change applies from the next reply in each conversation, without restarting the agent and without any of them losing its thread.

Conversations you pinned to a model of their own keep it. If you want all of them on the agent's model, tick Apply to all, next to the Model title, before saving: those with their own model or connection go back to the agent's from their next reply. You can tick it without changing the model, to bring them all back to the one the agent already has. As with any model change, those conversations lose their context cache.

Option	When it is useful
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.

Changing connection or provider while the agent is running does not restart it. The previous credential stays in its environment until you restart it. If a key has leaked, revoke it at the provider and restart the agents that used it: changing or removing it in Kujira is not enough.

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 from the organization. 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.