Models
Three ways to give the agent a model — connect a provider with one key, switch on a coding agent installed on this machine, or type in an endpoint of your own — and the two rules that trip everyone up.
Settings → Models. Two tabs across the top: Providers and Custom Models.
This page is where you make a model available. It isn't where you choose which model a conversation uses — that's the picker in the chat composer, per conversation.
Everything here is remembered per machine, in files under ~/.semantix/USER/, so a model you
add is available in every project on this computer — and doesn't travel to another one.
Providers#
The tab has two lists, split by how a provider is reached.
API providers#
One key, the whole catalogue. Paste a provider's API key into its card and press Connect.
Semantix checks the key with the vendor before storing anything — a typo comes straight back as the
vendor's own error under the field, not as a broken picker later — then downloads the provider's
model list. Every model on it becomes searchable in the chat picker at once, with its context window
and prices already filled in, so cost readouts work without you typing a thing.
A connected card reads something like sk-or…3f8f · 446 models · refreshed 2m ago, and carries
three controls: Refresh models re-downloads the list, Rotate key opens the field again for a
new key, and Disconnect asks once (Its models leave the picker) and removes it.
There is no Add button: the list is the registry, and a vendor appears here when Semantix knows how to talk to it. In this build that means OpenRouter.
Note
The catalogue is a snapshot. A model the provider added since you connected won't appear until you press Refresh.
The key is written to ~/.semantix/USER/providers.json; the downloaded catalogue to
~/.semantix/USER/catalogs/, which holds nothing secret. Models you star in the picker are kept in
~/.semantix/USER/favorite-models.json, and a starred model is what a new agent in the composer
picks by default.
CLI providers#
Coding agents installed on this machine, each with its own sign-in. These aren't endpoints Semantix calls with a key; they're programs on your computer that bring their own login and their own models, and Semantix drives them for you.
Claude Code is always on the list, on by default wherever the claude command can run. Its
status reads Ready, Off, or Not signed in — run claude once in a terminal to sign in.
Semantix never asks for your Anthropic credentials — it uses the sign-in the claude command
already has.
Below it, any other agent Semantix knows how to drive — Cursor, Copilot, Gemini,
OpenCode — appears with a status: Not installed on this machine, Off, Signed out, or
N models once it's on and answering. Some sign in through a browser, some through an API key you
add on the card.
Each card has an on/off switch. Off means the agent's models leave the chat picker; nothing is
uninstalled or signed out. The switches are remembered in ~/.semantix/USER/cli-providers.json.
Note
CLI providers are for conversations. They never appear in the Studio page's Primary and Secondary seats, in the Task Manager's model picker, or anywhere else Semantix has to call a model itself from the background — those lists offer API-key models only.
Custom Models#
This tab is for endpoints you type in by hand. Anything with an OpenAI-compatible or Anthropic-compatible API — Groq, Together, Fireworks, DeepSeek, a Claude proxy, a model running locally under Ollama, your company's internal gateway — becomes a model you can pick in any conversation.
Adding one#
Add model opens a form. Four fields are required — Name, Base URL, Model ID, and
API Key — and the Create button stays greyed out until all four are filled. It doesn't tell you
which one is missing, so if it won't light up, check the key.
Name is yours; it's what appears in the model picker, labelled Custom. Llama 3.1 70B (Groq).
Provider preset is a shortcut, not a setting. Picking one fills in the Base URL; the control is just a mirror of that field, so editing the URL by hand changes what it shows. Nothing separate is stored.
Base URL is the field that goes wrong, because the rule inverts depending on the protocol below it:
- OpenAI-compatible (chat/completions) — include the version path.
https://api.groq.com/openai/v1, nothttps://api.groq.com. The URL is used exactly as you typed it. - Anthropic (Messages API) — leave the version path off.
https://api.kie.ai/claude, not.../v1. Semantix appends the rest.
Every shipped preset already has the OpenAI form right, so if you started from one, don't add to it.
Model ID is the provider's exact model string, sent verbatim: llama-3.1-70b-instruct. A typo
here won't be caught until you use it.
API protocol picks between the two shapes above. Choose Anthropic for Claude-compatible sources.
API Key is masked, with an eye to reveal it.
Alias, Context window and the two $/1M tok fields are optional. Context window sizes the context gauge in chat — leave it blank and Semantix assumes 128,000, which will read wrong for a model with a different window. The prices are a fallback: most OpenAI-compatible endpoints don't report billing, so Semantix works cost out from your numbers instead. If the provider does report a cost, that wins.
Fill neither price and cost shows as a dash. Fill only one and the other side is counted as free — you get a confidently wrong low number rather than a blank.
Note
The three number fields quietly ignore anything that isn't a positive number — including 0. A
rejected value isn't flagged; the field simply behaves as if you'd left it empty.
Nothing is checked when you save#
Unlike a provider connection, no verification of any kind happens when you create a custom model. A wrong base URL, a dead key, a model id that doesn't exist — all three save cleanly and appear in your picker as though everything is fine.
You find out at first use. Select the model, send a message, and the turn fails in the chat with the provider's error. That's the only place the truth surfaces, so when a new model doesn't work, read the failed turn rather than coming back here.
Editing and deleting#
Edit reopens the form with everything filled in except the key, which is deliberately blank
and marked •••••••• (unchanged). Leave it alone to keep the stored key; type a new one to rotate
it. There's no way to read back a key you've saved.
Delete asks once and removes it immediately. No undo.
If you delete a model a conversation was using, that conversation isn't quietly moved to another
model. Its picker reads Select Model, Send is disabled with Select a model first, and you choose.
Scheduled runs and flows are blunter: they fail with model "<id>" is not in custom-models.json — was it removed from your Semantix models?
Where your keys are stored#
Your custom models and their keys are written to a plain JSON file on your machine:
~/.semantix/USER/custom-models.json
The keys are stored in plain text, here and in providers.json. On Linux and macOS the files
are created readable only by your own user account; on Windows they get no special permissions.
Nothing is encrypted, and the keys are readable by anything that can reach the on-device Semantix
server.
Treat those files like any other secrets file. Use scoped, revocable keys where your provider offers them, and remember that a home-directory backup or a synced home directory carries your keys with it.
What this page doesn't do#
It doesn't set temperature, token limits or system prompts. It doesn't choose the model for a conversation. And it doesn't hold the two seats Semantix uses for its own background work — those are on the Studio page, and they only accept models from this page's API-key half.