Providers & Models

@zlogic.run only talks to providers you configure. There is no @zlogic.run cloud — requests go directly to the endpoints you declare.

⚠️ Beta disclaimer

Only DeepSeek and OpenAI are currently fully tested. Every other SDK (anthropic, gemini, glm, dashscope, qwen_local, openrouter, fireworks, bedrock, openai_generic) is in beta status — it should work, but expect rough edges. If something breaks, please file an issue: https://github.com/zlogic-labs/zlogic/issues.

Built-in providers

A built-in provider directory ships with the program (endpoints, context windows, pricing and thinking tiers). Built-ins appear automatically once a key is found — no config file entry needed:

Provider	SDK	Key source (auto-detected)
OpenAI	openai_chat / openai_responses	OPENAI_API_KEY or system keyring
Anthropic	anthropic	ANTHROPIC_API_KEY or keyring
Gemini	gemini	GEMINI_API_KEY / GOOGLE_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY or keyring
DeepSeek	deepseek	DEEPSEEK_API_KEY or keyring
GLM (智谱)	glm	ZHIPUAI_API_KEY / GLM_API_KEY or keyring
DashScope (Qwen)	dashscope	DASHSCOPE_API_KEY or keyring
OpenRouter	openrouter	OPENROUTER_API_KEY or keyring
xAI	openai_generic	XAI_API_KEY or keyring
Groq	openai_generic	GROQ_API_KEY or keyring
OpenCode Go	openai_generic	OPENCODE_API_KEY or keyring
Fireworks	fireworks	detected from the environment
Bedrock	bedrock	detected from the environment

See Key Management for how keys are resolved.

Self-hosted & custom endpoints

SDK	Use for
qwen_local	self-hosted Qwen (vLLM / SGLang with reasoning enabled)
openai_generic	any other OpenAI-compatible endpoint — enterprise gateways, self-hosted vLLM/SGLang; supports a declarative dialect for reasoning fields

Adding a provider in models.yaml

# ~/.config/zlogic/models.yaml
auto_detect_env: true        # default true — read keys from environment variables

providers:
  my-provider:
    sdk: openai_chat         # SDK protocol (see the table above)
    base_url: https://api.openai.com/v1
    models:
      gpt-4o: {}
      gpt-4o-mini: {}

Provider-level fields: sdk, base_url, wiring (headers / query params / extra headers — e.g. Azure-style auth), default_params, models, and enabled: false to switch a provider off. guide_url is display-only.

API keys are never written into configuration — they come from the environment (on by default) or the OS keyring. There is no api_key field.

Keys from environment variables

Environment-based keys are on by default (auto_detect_env: true). Export the variable and the provider is picked up — no key add needed:

export DEEPSEEK_API_KEY=sk-...

The generic pattern is <PROVIDER>_API_KEY (provider id uppercased); built-ins also recognize their official variable names (see the table above). Set auto_detect_env: false in models.yaml to disable environment keys entirely — then only the system keyring is consulted.

Model settings

Each model under a provider can carry:

providers:
  my-provider:
    models:
      gpt-4o:
        wire_model: gpt-4o-2024-11-20   # model name actually sent to the API (default: the key)
        display_name: GPT-4o             # shown in the UI
        tier: main                       # light / main / thinking
        context_window: 128000           # tokens; used for compaction decisions
        max_output_tokens: 16384
        vision: true                     # capability flag
        thinking:                        # thinking capability (per-model)
          supported: true
          can_disable: false
          efforts: [low, medium, high]   # effort levels the model accepts
        pricing:                         # per-million-token pricing (display + cost)
          input_per_m: 2.5
          output_per_m: 10.0
          cached_input_per_m: 0.5
          currency: USD
        default_params:                  # merged into the request body
          temperature: 0.6
        no_think_params:                 # used when thinking is turned off
          reasoning_effort: minimal

Supported standard params in default_params: temperature, top_p, top_k, max_tokens, frequency_penalty, plus vendor-specific extensions. If a context_window is missing, a conservative built-in floor is used per SDK (smaller values are safe — they only trigger compaction a little earlier). A model can also override the provider-level sdk when one provider mixes protocols.

Routing

• default_model in config.yaml picks the default model, written as provider:model (e.g. deepseek:deepseek-chat).
• Model tiers (light / main / thinking) supply fallbacks for auxiliary calls: when the conversation model is unavailable, titles / approvals / utility fall back to light, deep approval falls back to main.
• Role chains (llm_roles) declare per-role candidate chains that fall through on failure:

llm_roles:
  session:                  # main conversation
    models: [gpt-4o]
  compaction:               # context summarization
    models: [gpt-4o, claude-sonnet-4-6]
  title:                    # session titles — cheap is fine
    models: [gpt-4o-mini]
    params:
      temperature: 0.2
    thinking: off

Roles without a configured chain use built-ins, all starting from the current conversation model: titles/approvals/utility → session → light, deep approval → session → main, compaction and sub-agents → session — with no tiers configured, everything simply uses one model.

Built-in role names: session, title, compaction, approval, approval_deep, utility, agent:<name>.