Models โ
A list of models known to run with somora, grouped by engine, with the config.yaml values that work. The same model behaves differently behind each engine, so every entry is "this model behind this engine". Copy the block you need and adjust the host and key.
What you get โ
- Blocks you can copy. Each engine section has a ready
providers:block with ids, context windows and capabilities. - The right context window. The usable window depends on the engine and the server, not on the model card. The values here are the ones that work.
- Thinking levels that fit the model. Models disagree on the words for reasoning effort. The mappings here translate somora's levels.
- Vendor sampling defaults, set per model, so an agent does not need its own.
- Known pitfalls per engine, with the symptom and the fix.
Add a model โ
Copy the block for your engine from this page into
providers:inconfig.yaml. Aliases are suggestions: pick your own, each must be unique across the whole config.Reload the config:
/reloadin the TUI, the gear in the web taskbar, orPOST /config/reload. A change underproviders:needs no restart.Point an agent at it in its
agent.yaml:yamlmodel: fable # alias or provider/modelId fallback: deep4flash # optional, one ref or a listSend a message and check the model name in the chat header. For a reasoning model, compare
/thinking highwith/thinking lowand watch the ๐ง count.
How to read the tables โ
Each engine section has a table with a checked column.
| Value | Meaning |
|---|---|
| full check | The model went through somora's engine check on a live install. |
| partial | Only the parts named in the row were checked in somora. |
| in use | Runs in somora on a live install. Not taken through every step of the engine check. |
The full check covers: basic tools (time_now, exec, file_read, tmux, memory_search, a deferred tool), tools on an SSH resource (exec, file_write, file_read, file_list, tmux on another host), web_fetch, agent_ask to another agent, spawn_subagent, an image attachment where the model has vision, /thinking high, an abort in the middle of a turn, and session memory across turns.
The page is maintained by hand. Corrections and new rows are welcome as pull requests.
Claude Code subscription โ
Engine claude-cli. It runs through the Claude Agent SDK on your Claude login (somora claude login). There is no API key and no sampling: the CLI does not expose sampling parameters.
providers:
anthropic:
engine: claude-cli
models:
- id: claude-fable-5-2
alias: fable
contextWindow: 1000000
capabilities: [text, image, pdf, reasoning]
- id: claude-opus-5-5
alias: opus
contextWindow: 1000000
capabilities: [text, image, pdf, reasoning]
- id: claude-sonnet-5-5
alias: sonnet
contextWindow: 1000000
capabilities: [text, image, pdf, reasoning]
- id: claude-haiku-5-5
alias: haiku
contextWindow: 1000000
capabilities: [text, image, pdf, reasoning]| Model | contextWindow | Notes | Checked |
|---|---|---|---|
claude-fable-5-2 | 1000000 | The current Fable. It replaces claude-fable-5-1: keep your alias, change the id. Same surface: adaptive thinking always on, the thinking text is a placeholder. | in use |
claude-fable-5-1 | 1000000 | The previous Fable. Frontier model, adaptive thinking always on. The SDK discloses no thinking text for it, so somora shows a placeholder row that the model thought. No separate reasoning token count: it is part of tokens_out. | full check |
claude-opus-5-5 | 1000000 | Anthropic's recommendation for most workloads. It replaces claude-opus-5: keep your alias, change the id. Thinking text is a placeholder, as above. | full check |
claude-sonnet-5-5 | 1000000 | The current Sonnet: same surface as Opus, cheaper on the subscription budget. It replaces claude-sonnet-5: keep your alias, change the id. | in use |
claude-sonnet-5 | 1000000 | The previous Sonnet. | full check |
claude-haiku-5-5 | 1000000 | The current Haiku: fast and cheap, a good REM and background worker. Claude Code runs it with the full 1M window, five times its predecessor's. Thinks adaptively, keep reasoning in capabilities. It replaces claude-haiku-4-5. | in use |
claude-haiku-4-5 | 200000 | The previous Haiku. Supports extended thinking. Keep reasoning in capabilities. | full check |
What is special about this engine:
- The window is the model's real one. Claude Code runs the session against it and compacts by itself.
contextWindowonly decides whether the model is picked as a compaction worker and what the header percentage shows. - Most tools are found on demand. The everyday tools of
toolCatalogstay in the model's list; the others reach it throughToolSearch, so a call to one of them is preceded by aToolSearchrow. That is normal. - Thinking levels map to the SDK's
effort.low,mediumandhighgo through as they are,offdisables thinking. Areasoning.levelsblock has no effect on this engine. - No claude.ai connectors. Gmail, Calendar and Drive never exist inside a somora session.
ChatGPT subscription through Codex โ
Engine codex-cli. somora runs the bundled Codex (@openai/codex, the exact version is pinned in somora's package.json) as an app-server for each turn, on your codex login. A global codex on the host is not used. somora codex login signs in with the bundled one, and an existing codex login is picked up automatically.
providers:
openai:
engine: codex-cli
models:
- id: gpt-6-astra
alias: astra
contextWindow: 258400 # what codex reports as modelContextWindow
capabilities: [text, image, pdf, reasoning]
reasoning:
levels: { "off": low, high: xhigh } # Astra has no `minimal`: map `off` explicitly; `max` deliberately not a default
- id: gpt-6.1-sol
alias: sol
contextWindow: 258400 # the codex session window, NOT the 1.05M API window
capabilities: [text, image, pdf, reasoning]
reasoning:
levels: { high: xhigh } # optional: /thinking high โ codex xhigh
- id: gpt-6.1-terra
alias: terra
contextWindow: 475000 # what codex reports for 6.1 Terra
capabilities: [text, image, pdf, reasoning]
reasoning:
levels: { "off": low, high: xhigh } # refuses `minimal`: map `off` explicitly
- id: gpt-6-luna
alias: luna
contextWindow: 258400
capabilities: [text, image, pdf, reasoning]
- id: gpt-5.5
alias: gpt55
contextWindow: 258400
capabilities: [text, image, pdf, reasoning]The aliases above are named after the family (astra, sol, terra, luna), not the version. When OpenAI ships a new Sol, change the id and keep sol: agents, fallbacks and dream settings that name the alias move along.
| Model | contextWindow | Notes | Checked |
|---|---|---|---|
gpt-6-astra | 258400 | For the hardest problems. Runs in Code Mode only, like the 5.6 family. Effort words are low, medium, high, xhigh, max. There is no minimal, so map off as in the block above. | full check |
gpt-6.1-sol | 258400 | Flagship: complex coding, research, deepest reasoning. The current Sol. | in use |
gpt-6-sol | 258400 | The first GPT-6 Sol, followed by 6.1. | in use |
gpt-6-luna | 258400 | Fast and cheap: extraction, classification, volume. The current Luna. | in use |
gpt-5.6-sol | 258400 | The previous Sol. | full check |
gpt-6.1-terra | 475000 | The current Terra, the workhorse between Sol and Luna. Codex reports a 475000 window for it. It refuses minimal with HTTP 400, so map off: low as in the block above. | in use |
gpt-5.6-terra | 258400 | The previous Terra. OpenAI positions it as GPT-5.5 class at lower cost. | full check |
gpt-5.6-luna | 258400 | The previous Luna. | full check |
gpt-5.5 | 258400 | Still listed by Codex. The one model here that does not run in Code Mode only. Terra is the equivalent at lower cost. | full check |
gpt-5.4-mini, gpt-5.3-codex | none | Retired for ChatGPT accounts. Codex answers with an error, which shows as a failed turn or a crashed compaction worker. Remove them. | retired |
The Codex context window โ
Codex runs a session against a window it sets itself and reports on every turn as modelContextWindow: 258,400 for most models it offers and 475,000 for gpt-6.1-terra, while the API window of the same models is larger. Configure the number Codex reports for each model, not the number from the model card.
somora shows the reported number once the first turn has run. Until then the header uses the configured value. The configured value also decides whether the model is picked as a compaction worker, so keep it right. A higher value such as 272000 makes a long thread read as over full.
Codex compacts the thread itself. compaction.triggerRatio does not apply to this engine.
Thinking levels on Codex โ
The GPT-5.6 family knows minimal, low, medium, high, xhigh and max. somora sends its level under the same word, and off as minimal, unless you map it with reasoning.levels.
| You want | Mapping |
|---|---|
/thinking high to use xhigh | levels: { high: xhigh } |
off on a model without minimal | levels: { "off": low } |
| No effort sent for a level | levels: { medium: null } |
When Codex rejects an effort word, somora retries the turn once with the nearest word Codex lists and says so in the chat. For Astra with off unmapped that is low.
Tip
max is meant for the hardest problems, with cost and latency to match. Map it for a session when you need it, not as a default.
Codex sends reasoning summaries for each thinking phase. somora streams them as the thinking block.
Tools on Codex โ
somora hands its tools to Codex as dynamic tools, so every Codex model reaches the same tools as on the other engines. Codex's own tools are off: its shell, web search, apps, plugins, image tools, and its clock and sleep. What the model has besides somora's tools is Code Mode's own exec and wait. A test checks this against the bundled Codex, so an update that brings a new tool of its own is caught before release.
| Namespace | What is in it |
|---|---|
somora | somora's own tools |
somora_direct | tools whose results can carry images |
somora_mcp_<server> | tools of an external MCP server |
The tools of the shared list toolCatalog (Tools) sit in the model's direct list on every turn. The rest is deferred and found through Codex tool search. The developer instructions list their names.
Code Mode. The GPT-5.6 family and GPT-6 are code_mode_only. The model writes a JavaScript cell that calls tools.somora.<tool>(...) and finds deferred tools through ALL_TOOLS. Codex runs the cell, somora runs the tools. The cell has no require, process, fetch or filesystem. gpt-5.5 calls the same tools directly. somora codex debug models shows the tool_mode of each model.
Grok subscription โ
Engine grok-cli, for a SuperGrok or Premium subscription. somora runs the bundled Grok CLI (xAI's @xai-official/grok, the exact version is pinned in somora's package.json) over ACP for each turn. A grok installed on the host is used only on a platform somora ships no Grok build for, or when SOMORA_GROK_BIN names it. somora grok login signs in with the bundled one, and an existing grok login is picked up automatically. somora grok models lists the models your subscription offers.
providers:
xai:
engine: grok-cli
models:
- id: grok-4.7
alias: grok
contextWindow: 256000 # what Grok reports for the model
capabilities: [text, image, reasoning]| Model | contextWindow | Notes | Checked |
|---|---|---|---|
grok-4.7 | 256000 | Thinking levels are passed as --reasoning-effort. off is sent as low, because the model always reasons. reasoning.levels is applied. Images go to Grok as images, PDFs as page images. | yes: chat, tools, thinking text, images and PDFs, steering, stop, /compact, model switch and back |
Tools on Grok. The model has two tools of Grok's, search_tool and use_tool, and reaches only somora's tools through them. Grok's own built-ins (terminal, file edit, web search, its sub-agents and scheduler) are off. xAI account connectors that Grok would add from your account, such as tasks (automations) and cursor (your X account), are blocked in somora's Grok home. A connector a later Grok brings is logged (engine.grok_foreign_mcp) and blocked from the next turn on.
Grok compacts its own conversation near the end of the window, and a row in the chat says so. /compact asks Grok to compact now. A Grok model can also be the worker for REM, Deep, Lucid and compaction: each request runs in a fresh Grok session without tools, which is removed afterwards.
Self hosted models โ
Engine openai-compatible, for vLLM, SGLang, oMLX, Ollama, LM Studio and similar servers. This is the engine somora runs end to end: its own agent loop, sampling parameters, a reasoning vocabulary per model and its own compaction. The sampling values below are the vendors' recommended defaults for each model family.
providers:
local:
engine: openai-compatible
baseUrl: http://<your-host>:8000/v1
apiKey: "<key or anything for a local server>"
# sendUserTag: true # default: `user: "<agent>/<session>"` on every request so a
# gateway can attribute spend per agent; false to withhold
models:
- id: deepseek-v4-flash # SGLang; behind LiteLLM use the route name (e.g. deepseek-v4-flash-0731)
alias: deep4flash
contextWindow: 700000 # = the server's --context-length, not the model's 1M
capabilities: [text, reasoning]
sampling: { temperature: 1.0, top_p: 0.95 }
reasoning:
levels: { medium: high, high: max }
- id: deepseek-v4.1-flash # SGLang TP=4 (community SM120 runtime), Engram NVMe offload
alias: deep41flash
contextWindow: 700000 # = --context-length
capabilities: [text, image, reasoning]
sampling: { temperature: 1.0, top_p: 0.95 }
maxTokens: 16384 # operational output budget INCLUDING reasoning, not the model's max
reasoning:
levels: { "off": none, low: low, medium: high, high: max }
builder: { maxTokens: 65536, thinking: medium } # builders write whole files and think before each
- id: glm-5.3-flash # vLLM TP=4, native FP8; behind LiteLLM use the route name
alias: glm
contextWindow: 700000 # = --max-model-len (model-native 1M; 262k in the reference recipe)
capabilities: [text, image, reasoning]
sampling: { temperature: 1.0, top_p: 0.95 } # = the model's generation_config.json (vLLM applies it when nothing is sent)
maxTokens: 16384
reasoning:
levels: { "off": low, low: low, medium: high, high: max } # vocabulary is ONLY low/high/max; anything else = max
- id: deepseek-v4-flash-vision-exp # SGLang TP=2, same backbone as deepseek-v4-flash + ViT; experimental
alias: deep4vision
contextWindow: 700000 # = --context-length (KV pool 859k tokens at mem-fraction 0.90)
capabilities: [text, image, reasoning]
sampling: { temperature: 1.0, top_p: 0.95 } # as deepseek-v4-flash
reasoning:
levels: { medium: high, high: max } # as deepseek-v4-flash
- id: qwen3.8-flash-next # vLLM, FP8
alias: qwen38next
contextWindow: 524288 # = --max-model-len (YaRN)
capabilities: [text, image, reasoning]
sampling: { temperature: 0.6, top_p: 0.95, top_k: 20, min_p: 0 }
maxTokens: 16384
reasoning:
levels: { "off": low, high: xhigh }
- id: qwen3.5-397b-a17b-awq # vLLM, AWQ INT4
alias: qwen35big
contextWindow: 262144
capabilities: [text, image, reasoning]
sampling: { temperature: 0.6, top_p: 0.95, top_k: 20, min_p: 0 }
reasoning:
levels: { "off": low, high: xhigh }
- id: qwen3.8-27b-fp8 # vLLM, dense
alias: qwen38small
contextWindow: 262144
capabilities: [text, image, reasoning]
sampling: { temperature: 0.6, top_p: 0.95, top_k: 20, min_p: 0 }
reasoning:
levels: { "off": low, high: xhigh }
- id: kolibri-1 # vLLM with Aleph Alpha's inference plugin, FP8
alias: kolibri
contextWindow: 262144 # = --max-model-len (the model is validated up to 1M)
capabilities: [text, reasoning] # no vision
sampling: { temperature: 1.0, top_p: 0.97, top_k: 128 } # the model's generation_config.json
maxTokens: 16384
reasoning:
levels: { "off": none } # the other levels pass as they are
- id: gemma-4-31b-it-8bit # oMLX (Apple Silicon)
alias: gemma4big
contextWindow: 131072
capabilities: [text, image]
sampling: { temperature: 1.0, top_p: 0.95, top_k: 64 }
- id: gemma-4-26b-a4b-it-4bit # oMLX
alias: gemma4small
contextWindow: 131072
capabilities: [text, image]
sampling: { temperature: 1.0, top_p: 0.95, top_k: 64 }Server, window and sampling โ
Sampling is given as temperature / top_p / top_k.
| Model family | Server | contextWindow | Sampling | Checked |
|---|---|---|---|---|
| DeepSeek V4 Flash (284B MoE, 13B active) | SGLang, TP=4 | the server's --context-length: 700000 on a two GPU profile, 1M only with the whole box | 1.0 / 0.95 (DeepSeek's recommendation for agents and coding) | full check, image attachment refused as intended |
| DeepSeek V4.1 Flash | SGLang, TP=4, community SM120 runtime, Engram NVMe offload | --context-length 700000 | 1.0 / 0.95 (model card; top_k and penalties unset) | partial: thinking levels, native image, tools, several turns |
| GLM-5.3-Flash (321B MoE, 18B active) | vLLM, TP=4, native FP8, MTP-4, fp8 KV | --max-model-len 700000 (KV pool 1.16M tokens with --kv-cache-memory 7.5 GiB) | 1.0 / 0.95 (the model's generation_config.json) | in use |
| DeepSeek-V4-Flash-Vision-Exp (284B MoE, 13B active, 0.5B ViT) | SGLang, TP=2, preview image with sm_120 patches | --context-length 700000 (pool 859k at mem-fraction 0.90; 0.85 gives only 203k) | 1.0 / 0.95 | in use |
| Qwen3.8-Flash-Next FP8 (176B, 6B active) | vLLM, TP=4 | --max-model-len, 524288 with YaRN 2.0; 1048576 with YaRN 4.0 on a four GPU server | 0.6 / 0.95 / 20, min_p 0 (Qwen's thinking mode defaults) | full check |
| Qwen3.5-397B-A17B AWQ INT4 | vLLM, TP=4 | 262144 (max_model_len) | as Qwen3.8-Flash-Next | full check |
| Qwen3.8-27B FP8, dense | vLLM, 1 GPU | 262144 | as Qwen3.8-Flash-Next | full check |
| Kolibri-1 FP8 (78B MoE, 3.5B active), German and English | vLLM 0.29 with Aleph Alpha's inference plugin, 1 GPU | --max-model-len 262144 (validated up to 1M) | 1.0 / 0.97 / 128 (the model's generation_config.json) | in use |
| Gemma 4 31B and 26B-A4B | oMLX | 131072 | 1.0 / 0.95 / 64 (Gemma team recommendation) | full check |
Reasoning levels per family โ
| Model family | Words the model accepts | An unknown word | Map |
|---|---|---|---|
| DeepSeek V4 Flash, Vision-Exp | low, high, max | is ignored | medium: high, high: max. No mapping for off: leaving the parameter out gives no reasoning, and so does none. |
| DeepSeek V4.1 Flash | none, low, high, max | is ignored | off: none, medium: high, high: max |
| GLM-5.3-Flash | low, high, max only | silently becomes max, also none and medium | off: low, medium: high, high: max |
| Qwen 3.x | none, low, medium, xhigh | answers 400, so high fails unless mapped | high: xhigh and off: low or off: none, see below |
| Kolibri-1 | none, minimal, low, medium, high, xhigh, max | unchecked | off: none. none gives zero reasoning. |
| Gemma 4 | none, no reasoning capability | not sent | nothing |
Details that matter when you pick a mapping:
- Qwen thinks when nothing is sent. Without a mapping,
offsends no parameter and the model reasons at its default.nonegives zero reasoning tokens on Qwen3.8-Flash-Next. On the two other Qwen modelsnoneis unchecked: keepoff: lowthere. - Qwen
off: loworoff: none. Useoff: lowfor an agent that talks to people,off: nonefor a worker whose output is parsed. The thinking guide explains why. - GLM
maxis expensive. The model writes whole solutions inside its reasoning and runs into the output cap. Usehigh: maxonly on purpose. With GLM, top-levelreasoning_effortandchat_template_kwargs.reasoning_effortare equivalent. - DeepSeek V4.1 reasoning length varies. It does not rise steadily with the level.
- DeepSeek V4 Flash can reason inline. On longer prompts without the parameter, reasoning can arrive in the text, ending in
</think>. somora moves it to the thinking channel.
Warning
Always map off to the family's lowest level and test with a one line prompt: the reasoning must be empty. The none that switches Qwen off means full reasoning on GLM.
When no level is set โ
With no level for the session, the agent or the model, somora sends nothing and the backend decides. What that means differs per family. A reasoning.default on the model makes the choice visible in every client. Set it to the level that matches what the model does anyway, or on purpose to a different one.
| Model family | Nothing set | Default worth setting |
|---|---|---|
| DeepSeek V4 Flash, Vision-Exp | No reasoning. | Only when the agent should think. default: medium sends high. |
| DeepSeek V4.1 Flash | Unchecked. | Leave it unset until you have compared the lengths. |
| GLM-5.3-Flash | Unchecked. An unknown word becomes max, which is expensive. | Compare first. default: medium sends high. |
| Qwen3.8-Flash-Next | Reasons as much as with xhigh. | default: high: the same behaviour, now shown as high. |
| Kolibri-1 | Reasons: its chat template defaults to high. | default: high: the same behaviour, now shown as high. |
| Gemma 4 | No reasoning capability. | None. |
- id: qwen3.8-flash-next
reasoning:
levels: { "off": low, high: xhigh }
default: high # what the model does without a levelAn agent's thinking: in agent.yaml and a session's /thinking still come first. The thinking guide lists the order.
Notes per family โ
| Model family | Vision | Tool calls and other notes |
|---|---|---|
| DeepSeek V4 Flash | no | Streams reasoning_content, full thinking text in the chat. Tool calls are parsed by the server. |
| DeepSeek V4.1 Flash | native, no analyze_file worker needed | maxTokens: 16384 is an operational budget that includes reasoning. |
| GLM-5.3-Flash | native | Tool calls through the glm47 parser, reasoning through glm45. All four GPUs: an exclusive profile. vLLM applies the sampling values on the server when the request has none (--generation-config auto). |
| DeepSeek-V4-Flash-Vision-Exp | yes; small text OCR is shaky, screenshots and charts are fine | Tool calls through the deepseekv4 parser. Text and agent quality as V4 Flash. Experimental according to DeepSeek. |
| Qwen3.8-Flash-Next | yes | maxTokens: 16384, because reasoning otherwise eats short answers. Parsers qwen3 and qwen3_xml. |
| Qwen3.5-397B-A17B | yes | hermes tool parser. |
| Qwen3.8-27B | yes | qwen3_coder tool parser. |
| Kolibri-1 | no | Tool calls work over many turns, with several tools per turn. Without off: none an agent set to off still reasons. |
| Gemma 4 | yes | A prefill memory guard answers 400 on long prompts. somora's reactive compaction handles it. |
What is special about this engine โ
contextWindowis the compaction wall. somora compacts atcompaction.triggerRatio(default 0.8) of the window, lessmaxTokenswhen set. Use the server's limit, not the model card's. With 1000000 configured against a 700k server, the server answers400 ContextWindowExceededErrorbefore somora compacts.- A router in front changes the rules. LiteLLM drops
reasoning_effortunless the model'sallowed_openai_paramslists it. Every level then answers 200 with the same amount of reasoning. Fix it in the router, then compare/thinking highwith/thinking lowand the ๐ง count. - A self hosted build can be a community runtime. The DeepSeek V4.1 row was measured on a community SM120 image with NVMe offload, not on stock SGLang. Treat its numbers as that setup's behaviour.
- vLLM applies the model's
generation_config.jsonwhen a request sends no sampling (--generation-config auto, its default). Thesampling:block in somora then documents the value. SGLang does not do this. - A rejected sampling key is dropped once. When the server answers 400 to a sampling parameter, somora retries the request without sampling and says so in the chat.
- Estimated reasoning count. A server that streams reasoning but reports no
reasoning_tokensgets an estimated ๐ง count with a tilde. - A catalog, or every tool. By default the model gets the everyday tools plus
tool_searchandtool_call, and the rest is named at the end of the system prompt. Rows show the tool that ran, nottool_call.toolCatalogwithmode: all(for the engine or for one model) sends every tool with its full description on each request. See Tools.
Which engines can be workers โ
| Worker | Engines |
|---|---|
Vision worker for analyze_file | openai-compatible only |
| REM, Deep, Lucid, compaction | openai-compatible, claude-cli, codex-cli, grok-cli |
Hosted models through OpenRouter โ
The same openai-compatible engine with three differences: reasoning goes as a nested reasoning: { effort } object (set reasoning.param: reasoning), PDFs can go natively (pdfMode: native) and images travel as data URLs.
providers:
openrouter:
engine: openai-compatible
baseUrl: https://openrouter.ai/api/v1
apiKey: "<your key>"
pdfMode: native
models:
- id: anthropic/claude-haiku-4.5
alias: orhaiku
contextWindow: 200000
capabilities: [text, image, pdf]
- id: minimax/minimax-m3
alias: minimax3
contextWindow: 1048576
capabilities: [text, image, reasoning]
sampling: { temperature: 1.0, top_p: 0.95, top_k: 40 }
reasoning: { param: reasoning }
- id: moonshotai/kimi-k3
alias: kimi3
contextWindow: 1048576
capabilities: [text, image, reasoning]
reasoning: { param: reasoning }
- id: deepseek/deepseek-v4-pro-0813
alias: deep4pro
contextWindow: 1048576
capabilities: [text, reasoning]
sampling: { temperature: 1.0, top_p: 0.95 }
reasoning: { param: reasoning }| Model | contextWindow | Sampling | Notes | Checked |
|---|---|---|---|---|
anthropic/claude-haiku-4.5 | 200000 | none | Useful as the last, always reachable vision worker in a vision.worker chain. The subscription Haiku cannot be one, because CLI engines are not vision workers. Costs API money. | full check |
minimax/minimax-m3 | 1048576 | 1.0 / 0.95 / 40 (model card) | Image and video input. Reasoning words low, medium, high match somora's, no levels needed. | full check |
moonshotai/kimi-k3 | 1048576 | none, on purpose | Moonshot fixes temperature 1.0 and top_p 0.95 on the server and documents "leave the parameters out". Reasoning words low, medium, high. | full check |
deepseek/deepseek-v4-pro-0813 | 1048576 | 1.0 / 0.95 | No vision. The hosted big sibling of a local V4 Flash: a good fallback when the local box is off. | full check |
Warning
Watch the fallback. When a hosted key expires, the agent's fallback model answers the turn. The chat header shows that model and the turn carries a fallback chip. Check the header, not just the reply.
Decision models โ
Models that answer typed questions instead of writing text, used by the decision_evaluate tool. They have their own decisions block in config.yaml, separate from providers, and are never picked as a chat model.
decisions:
model: clef
models:
- name: clef
baseUrl: https://<your-host>/clef
apiKey: <key>
model: clef
capabilities: [text, image]| Model | Where it runs | Images | Input limit | Checked |
|---|---|---|---|---|
| Clef | Self-hosted, Cloudflare's open decision model | yes, up to 4 per call | what the server reports at /v1/models | yes: all three question types, images, the limit, refusal of too long input |
| OneJev 1.6 9B | Self-hosted on a Flide server | yes; somora sends them in Flide's form | set maxInputTokens (32768 on Flide; its /v1/models names none) | yes: text questions, images, Flide's length refusal |
| Jev | TypeSafe AI, hosted | no | per its documentation | no: not tested with somora |
Clef's answer time grows with the input: a short request takes well under a second, four images or tens of thousands of tokens take tens of seconds. OneJev answers a short request in about 0.1 to 0.2 seconds. Jev speaks the same API by its public description; somora was checked against Clef and OneJev only. How images differ between the servers is in decision models.
Settings โ
A model entry with every field. Only id and contextWindow are required.
providers:
<name>:
engine: openai-compatible # claude-cli | codex-cli | grok-cli | openai-compatible
baseUrl: http://<your-host>:8000/v1
apiKey: "<key>"
pdfMode: rasterize
memoryInjectMode: inline-user
sendUserTag: true
models:
- id: <model-id>
alias: <alias>
contextWindow: 262144
capabilities: [text]
maxTokens: 16384
parallelToolCalls: false
sampling: { temperature: 0.6, top_p: 0.95 }
reasoning:
param: reasoning_effort
levels: { "off": low, high: xhigh }Model fields โ
| Field | Default | openai-compatible | claude-cli | codex-cli | grok-cli |
|---|---|---|---|---|---|
contextWindow | required | compaction trigger, worker choice, display. Use the server's limit. | worker choice, display. The native window is right. | worker choice, display. Use the window Codex reports for the model: 258400, or 475000 for gpt-6.1-terra. | display. Grok reports the window itself, and that number is shown. |
capabilities | [text] | image and pdf gate attachments, reasoning decides whether a thinking level is sent | same | same | same |
alias | none | short name for model: in agent.yaml, letters, digits, - and _ | same | same | same |
reasoning.default | unset | the thinking level used when session and agent set none, in somora's words; sent explicitly and shown as the model's default | same | same | same |
reasoning.levels | unset | somora level to the word the model gets, for off, low, medium, high. null leaves the parameter out. | not used | applied, for example xhigh and max | applied |
reasoning.param | reasoning_effort | where the word goes: reasoning_effort, nested reasoning for OpenRouter, or chat_template_kwargs | not used | not used | not used |
sampling | unset | sent on every call, dropped once when the server rejects a key | not used | not used | not used |
maxTokens | unset, nothing sent | output cap on every call, dream and compaction workers included | not used | not used | not used |
builder.maxTokens | unset | replaces maxTokens when a builder runs on this model | not used | not used | not used |
builder.thinking | unset | replaces reasoning.default for builders; an agent's or session's own level still wins | same | same | same |
parallelToolCalls | unset | unset or false: the model is asked for one tool call per round. true lets a model you trust call several tools at once; calls of tools that only read then run at the same time (Tools). | not used | not used | not used |
Keys allowed in sampling: temperature, top_p, top_k, min_p, frequency_penalty, presence_penalty, repetition_penalty, seed, stop. The sampling guide has the details.
Provider fields โ
These exist only on an openai-compatible provider. The three CLI engines take engine and models and nothing else.
| Field | Default | Meaning |
|---|---|---|
baseUrl | required | Address of the server's OpenAI style API. |
apiKey | required | The key. Any text for a local server that checks none. |
pdfMode | rasterize | rasterize sends PDF pages as images and works with every vision model. native sends the PDF itself: only for a backend that accepts it. |
memoryInjectMode | inline-user | Where recalled notes go: inline-user puts them in the user message and keeps the prefix cache, system appends them to the system prompt. |
sendUserTag | true | Sends user on every request so a gateway can group cost per agent and session. false withholds it. |
dropMemoryBlocksAfterIdleMinutes | 60 | After this many idle minutes the memory blocks of earlier turns leave the rebuilt conversation. Match it to the provider's cache lifetime; 0 keeps them. See Memory. |
The user value that sendUserTag sends:
| Request | Value |
|---|---|
| Chat turn | <agent>/<session> |
| REM | <agent>/rem |
| Deep | <agent>/deep |
| Lucid | lucid/<pass> |
| Compaction | <agent>/compaction |
| Vision worker | <agent>/analyze_file |
LiteLLM stores this value in the end_user column of its spend logs, not in user.
Related settings โ
| Setting | Default | Where | Meaning |
|---|---|---|---|
fallback | unset | agent.yaml | One model or an ordered list. Used on every engine when the model fails before it wrote text or ran a tool. |
fallback.retryUnavailableMinutes | 60 | config.yaml | A model that was unreachable is skipped for this many minutes. |
compaction.triggerRatio | 0.8 | config.yaml | Share of the window at which somora compacts. openai-compatible only. |
toolCatalog | the everyday core tools | config.yaml | somora tools in the model's direct list on claude-cli and codex-cli, and on openai-compatible unless its mode is all. Takes effect on the next turn. |
Minimum versions โ
- Node.js 22.22.2 or newer. Every
somoracommand refuses an older Node. - Claude Code, Codex and the Grok CLI need no separate install. somora bundles the exact versions pinned in its
package.json. A Claude Code you installed yourself is used instead when present.
A CLI engine's tools and lock-down are checked again after every CLI update.
Troubleshooting โ
| Symptom | Cause and fix |
|---|---|
400 ContextWindowExceededError before somora compacts | contextWindow is above the server's limit. Set it to the server's --context-length or --max-model-len. |
| The header says the context is over full on a Codex model | contextWindow is not the window Codex reports: 258400, or 475000 for gpt-6.1-terra. |
| A Codex turn fails at once, or a compaction worker crashes | The model id is retired. Remove gpt-5.4-mini and gpt-5.3-codex. |
| A chat row says the model rejected the reasoning effort | The model does not know the word. Map the level in reasoning.levels. The log line is engine.reasoning_effort_rejected. |
| Every thinking level gives the same amount of reasoning | A router drops reasoning_effort. Allow the parameter in the router. |
/thinking off still reasons | off is unmapped and the model thinks by default, or the model treats none as full reasoning. Map off for that family. |
| A chat row says the sampling parameters were rejected | Remove the key the server names from the model, agent or session sampling. The log line is engine.sampling_rejected. |
| Another model answered | The agent's fallback took over. The engine.fail line in the server log has the reason, for example 401 API key expired. |
See also โ
- Setup: logging in to Claude Code, Codex and Grok, and connecting a local server
- Thinking: thinking levels, vocabularies per model, which engines show thinking text
- Sampling: the sampling keys and where they can be set
- Compaction: what
contextWindowcontrols and which model summarises - Agents:
modelandfallbackinagent.yaml - Security: what a CLI engine can reach inside a somora session
- Decision models: the
decisionsblock and thedecision_evaluatetool