Skip to content

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 โ€‹

  1. Copy the block for your engine from this page into providers: in config.yaml. Aliases are suggestions: pick your own, each must be unique across the whole config.

  2. Reload the config: /reload in the TUI, the gear in the web taskbar, or POST /config/reload. A change under providers: needs no restart.

  3. Point an agent at it in its agent.yaml:

    yaml
    model: fable          # alias or provider/modelId
    fallback: deep4flash  # optional, one ref or a list
  4. Send a message and check the model name in the chat header. For a reasoning model, compare /thinking high with /thinking low and watch the ๐Ÿง  count.

How to read the tables โ€‹

Each engine section has a table with a checked column.

ValueMeaning
full checkThe model went through somora's engine check on a live install.
partialOnly the parts named in the row were checked in somora.
in useRuns 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.

yaml
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]
ModelcontextWindowNotesChecked
claude-fable-5-21000000The 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-11000000The 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-51000000Anthropic'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-51000000The 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-51000000The previous Sonnet.full check
claude-haiku-5-51000000The 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-5200000The 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. contextWindow only 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 toolCatalog stay in the model's list; the others reach it through ToolSearch, so a call to one of them is preceded by a ToolSearch row. That is normal.
  • Thinking levels map to the SDK's effort. low, medium and high go through as they are, off disables thinking. A reasoning.levels block 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.

yaml
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.

ModelcontextWindowNotesChecked
gpt-6-astra258400For 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-sol258400Flagship: complex coding, research, deepest reasoning. The current Sol.in use
gpt-6-sol258400The first GPT-6 Sol, followed by 6.1.in use
gpt-6-luna258400Fast and cheap: extraction, classification, volume. The current Luna.in use
gpt-5.6-sol258400The previous Sol.full check
gpt-6.1-terra475000The 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-terra258400The previous Terra. OpenAI positions it as GPT-5.5 class at lower cost.full check
gpt-5.6-luna258400The previous Luna.full check
gpt-5.5258400Still 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-codexnoneRetired 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 wantMapping
/thinking high to use xhighlevels: { high: xhigh }
off on a model without minimallevels: { "off": low }
No effort sent for a levellevels: { 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.

NamespaceWhat is in it
somorasomora's own tools
somora_directtools 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.

yaml
providers:
  xai:
    engine: grok-cli
    models:
      - id: grok-4.7
        alias: grok
        contextWindow: 256000          # what Grok reports for the model
        capabilities: [text, image, reasoning]
ModelcontextWindowNotesChecked
grok-4.7256000Thinking 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.

yaml
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 familyServercontextWindowSamplingChecked
DeepSeek V4 Flash (284B MoE, 13B active)SGLang, TP=4the server's --context-length: 700000 on a two GPU profile, 1M only with the whole box1.0 / 0.95 (DeepSeek's recommendation for agents and coding)full check, image attachment refused as intended
DeepSeek V4.1 FlashSGLang, TP=4, community SM120 runtime, Engram NVMe offload--context-length 7000001.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.95in 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 server0.6 / 0.95 / 20, min_p 0 (Qwen's thinking mode defaults)full check
Qwen3.5-397B-A17B AWQ INT4vLLM, TP=4262144 (max_model_len)as Qwen3.8-Flash-Nextfull check
Qwen3.8-27B FP8, densevLLM, 1 GPU262144as Qwen3.8-Flash-Nextfull check
Kolibri-1 FP8 (78B MoE, 3.5B active), German and EnglishvLLM 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-A4BoMLX1310721.0 / 0.95 / 64 (Gemma team recommendation)full check

Reasoning levels per family โ€‹

Model familyWords the model acceptsAn unknown wordMap
DeepSeek V4 Flash, Vision-Explow, high, maxis ignoredmedium: high, high: max. No mapping for off: leaving the parameter out gives no reasoning, and so does none.
DeepSeek V4.1 Flashnone, low, high, maxis ignoredoff: none, medium: high, high: max
GLM-5.3-Flashlow, high, max onlysilently becomes max, also none and mediumoff: low, medium: high, high: max
Qwen 3.xnone, low, medium, xhighanswers 400, so high fails unless mappedhigh: xhigh and off: low or off: none, see below
Kolibri-1none, minimal, low, medium, high, xhigh, maxuncheckedoff: none. none gives zero reasoning.
Gemma 4none, no reasoning capabilitynot sentnothing

Details that matter when you pick a mapping:

  • Qwen thinks when nothing is sent. Without a mapping, off sends no parameter and the model reasons at its default. none gives zero reasoning tokens on Qwen3.8-Flash-Next. On the two other Qwen models none is unchecked: keep off: low there.
  • Qwen off: low or off: none. Use off: low for an agent that talks to people, off: none for a worker whose output is parsed. The thinking guide explains why.
  • GLM max is expensive. The model writes whole solutions inside its reasoning and runs into the output cap. Use high: max only on purpose. With GLM, top-level reasoning_effort and chat_template_kwargs.reasoning_effort are 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 familyNothing setDefault worth setting
DeepSeek V4 Flash, Vision-ExpNo reasoning.Only when the agent should think. default: medium sends high.
DeepSeek V4.1 FlashUnchecked.Leave it unset until you have compared the lengths.
GLM-5.3-FlashUnchecked. An unknown word becomes max, which is expensive.Compare first. default: medium sends high.
Qwen3.8-Flash-NextReasons as much as with xhigh.default: high: the same behaviour, now shown as high.
Kolibri-1Reasons: its chat template defaults to high.default: high: the same behaviour, now shown as high.
Gemma 4No reasoning capability.None.
yaml
- id: qwen3.8-flash-next
  reasoning:
    levels: { "off": low, high: xhigh }
    default: high            # what the model does without a level

An agent's thinking: in agent.yaml and a session's /thinking still come first. The thinking guide lists the order.

Notes per family โ€‹

Model familyVisionTool calls and other notes
DeepSeek V4 FlashnoStreams reasoning_content, full thinking text in the chat. Tool calls are parsed by the server.
DeepSeek V4.1 Flashnative, no analyze_file worker neededmaxTokens: 16384 is an operational budget that includes reasoning.
GLM-5.3-FlashnativeTool 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-Expyes; small text OCR is shaky, screenshots and charts are fineTool calls through the deepseekv4 parser. Text and agent quality as V4 Flash. Experimental according to DeepSeek.
Qwen3.8-Flash-NextyesmaxTokens: 16384, because reasoning otherwise eats short answers. Parsers qwen3 and qwen3_xml.
Qwen3.5-397B-A17Byeshermes tool parser.
Qwen3.8-27Byesqwen3_coder tool parser.
Kolibri-1noTool calls work over many turns, with several tools per turn. Without off: none an agent set to off still reasons.
Gemma 4yesA prefill memory guard answers 400 on long prompts. somora's reactive compaction handles it.

What is special about this engine โ€‹

  • contextWindow is the compaction wall. somora compacts at compaction.triggerRatio (default 0.8) of the window, less maxTokens when set. Use the server's limit, not the model card's. With 1000000 configured against a 700k server, the server answers 400 ContextWindowExceededError before somora compacts.
  • A router in front changes the rules. LiteLLM drops reasoning_effort unless the model's allowed_openai_params lists it. Every level then answers 200 with the same amount of reasoning. Fix it in the router, then compare /thinking high with /thinking low and 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.json when a request sends no sampling (--generation-config auto, its default). The sampling: 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_tokens gets an estimated ๐Ÿง  count with a tilde.
  • A catalog, or every tool. By default the model gets the everyday tools plus tool_search and tool_call, and the rest is named at the end of the system prompt. Rows show the tool that ran, not tool_call. toolCatalog with mode: 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 โ€‹

WorkerEngines
Vision worker for analyze_fileopenai-compatible only
REM, Deep, Lucid, compactionopenai-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.

yaml
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 }
ModelcontextWindowSamplingNotesChecked
anthropic/claude-haiku-4.5200000noneUseful 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-m310485761.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-k31048576none, on purposeMoonshot 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-081310485761.0 / 0.95No 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.

yaml
decisions:
  model: clef
  models:
    - name: clef
      baseUrl: https://<your-host>/clef
      apiKey: <key>
      model: clef
      capabilities: [text, image]
ModelWhere it runsImagesInput limitChecked
ClefSelf-hosted, Cloudflare's open decision modelyes, up to 4 per callwhat the server reports at /v1/modelsyes: all three question types, images, the limit, refusal of too long input
OneJev 1.6 9BSelf-hosted on a Flide serveryes; somora sends them in Flide's formset maxInputTokens (32768 on Flide; its /v1/models names none)yes: text questions, images, Flide's length refusal
JevTypeSafe AI, hostednoper its documentationno: 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.

yaml
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 โ€‹

FieldDefaultopenai-compatibleclaude-clicodex-cligrok-cli
contextWindowrequiredcompaction 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 sentsamesamesame
aliasnoneshort name for model: in agent.yaml, letters, digits, - and _samesamesame
reasoning.defaultunsetthe thinking level used when session and agent set none, in somora's words; sent explicitly and shown as the model's defaultsamesamesame
reasoning.levelsunsetsomora level to the word the model gets, for off, low, medium, high. null leaves the parameter out.not usedapplied, for example xhigh and maxapplied
reasoning.paramreasoning_effortwhere the word goes: reasoning_effort, nested reasoning for OpenRouter, or chat_template_kwargsnot usednot usednot used
samplingunsetsent on every call, dropped once when the server rejects a keynot usednot usednot used
maxTokensunset, nothing sentoutput cap on every call, dream and compaction workers includednot usednot usednot used
builder.maxTokensunsetreplaces maxTokens when a builder runs on this modelnot usednot usednot used
builder.thinkingunsetreplaces reasoning.default for builders; an agent's or session's own level still winssamesamesame
parallelToolCallsunsetunset 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 usednot usednot 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.

FieldDefaultMeaning
baseUrlrequiredAddress of the server's OpenAI style API.
apiKeyrequiredThe key. Any text for a local server that checks none.
pdfModerasterizerasterize sends PDF pages as images and works with every vision model. native sends the PDF itself: only for a backend that accepts it.
memoryInjectModeinline-userWhere recalled notes go: inline-user puts them in the user message and keeps the prefix cache, system appends them to the system prompt.
sendUserTagtrueSends user on every request so a gateway can group cost per agent and session. false withholds it.
dropMemoryBlocksAfterIdleMinutes60After 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:

RequestValue
Chat turn<agent>/<session>
REM<agent>/rem
Deep<agent>/deep
Lucidlucid/<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.

SettingDefaultWhereMeaning
fallbackunsetagent.yamlOne model or an ordered list. Used on every engine when the model fails before it wrote text or ran a tool.
fallback.retryUnavailableMinutes60config.yamlA model that was unreachable is skipped for this many minutes.
compaction.triggerRatio0.8config.yamlShare of the window at which somora compacts. openai-compatible only.
toolCatalogthe everyday core toolsconfig.yamlsomora 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 somora command 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 โ€‹

SymptomCause and fix
400 ContextWindowExceededError before somora compactscontextWindow 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 modelcontextWindow is not the window Codex reports: 258400, or 475000 for gpt-6.1-terra.
A Codex turn fails at once, or a compaction worker crashesThe model id is retired. Remove gpt-5.4-mini and gpt-5.3-codex.
A chat row says the model rejected the reasoning effortThe 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 reasoningA router drops reasoning_effort. Allow the parameter in the router.
/thinking off still reasonsoff 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 rejectedRemove the key the server names from the model, agent or session sampling. The log line is engine.sampling_rejected.
Another model answeredThe 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 contextWindow controls and which model summarises
  • Agents: model and fallback in agent.yaml
  • Security: what a CLI engine can reach inside a somora session
  • Decision models: the decisions block and the decision_evaluate tool