Models and providers

You choose an endpoint and a model id. Veyyon then calls that provider’s API directly with your credentials. The endpoint can be a local server, a hosted API, or any OpenAI-compatible gateway.

• Contract (what the harness owns vs the provider): Model contract
• Copy-paste provider setups: Configuring providers
• Built-in provider stack internals: Provider stack and BYOK

API keys (BYOK)

BYOK means bring your own key. For a provider you configure yourself, Veyyon sends your key straight to that provider’s endpoint. There is no hosted proxy in between.

Set the key one of three ways:

• The provider’s environment variable (see Providers for the full map), or
• /login inside the TUI, which stores the credential in the auth store, or
• A models.yml apiKey on a custom provider (an env-var name, or literal:<text>).

See Signing in for storage modes and Configuring providers for full models.yml examples.

Minimal BYOK shape

# ~/.veyyon/profiles/default/agent/models.yml
providers:
  deepseek:
    baseUrl: https://api.deepseek.com
    api: openai-completions
    apiKey: DEEPSEEK_API_KEY
    models:
      - id: deepseek-chat
        name: DeepSeek Chat
        contextWindow: 128000
        maxTokens: 8192

$ export DEEPSEEK_API_KEY=sk-...
$ veyyon --model deepseek/deepseek-chat

Built-in providers

Veyyon ships a large built-in catalog (Anthropic, OpenAI, Google, Groq, OpenRouter, Mistral, xAI, Bedrock, and many hosted gateways) plus three auto-discovered local engines. A provider becomes selectable when it is not in disabledProviders and it is keyless or has resolvable credentials.

Once a provider is available, model ids come from a bundled static catalog, merged with live discovery for providers that expose a /models endpoint. Failed discovery returns an error; it does not invent an empty catalog.

Local models: Ollama and LM Studio

Both are discovered automatically once the engine is running; no models.yml entry and no key are required.

$ ollama serve
$ ollama pull llama3.2
$ veyyon                # then /model and choose an ollama/… entry

$ lms server start
$ veyyon                # then /model and choose an lm-studio/… entry

Override the base URL with OLLAMA_BASE_URL / LM_STUDIO_BASE_URL if a daemon listens elsewhere. An explicit models.yml entry for one of these ids replaces its built-in discovery.

Mid-session model switch

Switching the interactive model mid-session never blends through a fallback chain into the subagent or compaction model. /model shows the current interactive model; /session info shows session stats. veyyon plugin doctor checks plugin installation health.

$ veyyon --model openai/gpt-5
# later, inside the TUI:
/model deepseek/deepseek-chat
/session info

Model selection

# ~/.veyyon/profiles/default/agent/config.yml
modelRoles:
  default: openai/gpt-5          # interactive (persisted default)
  smol: openai/gpt-4.1-mini
  slow: anthropic/claude-opus-4-5:high
  plan: anthropic/claude-sonnet-5
subagent:
  model: deepseek/deepseek-chat:high
  agents:
    reviewer:
      enabled: true
      thinkingLevel: auto
compaction:
  model: openai/gpt-5-mini

Ctrl+P (default binding) cycles roles listed in cycleOrder (schema default smol, slow, not default). Full role list and aliases: Models, roles, and profiles.

Per-model harness settings

Prompt order, repair enablement, and tool exposure can be set per model id through harness profiles and model roles. See Execution-order prompts and Model contract.

Harness profiles

Optional overrides in config.yml or ~/.veyyon/profiles/default/agent/harness-profiles.yml. The two files take different shapes: config.yml nests under harness: (the harness.profiles setting), while harness-profiles.yml reads a top-level profiles: map (a top-level harness: key there is silently dropped).

# config.yml
harness:
  profiles:
    "openai/gpt-4.1":
      repair: true
      tools: ["read", "edit", "search", "bash", "write"]
      promptSectionOrder: ["tool-policy", "delivery-contract"]

# harness-profiles.yml
profiles:
  "openai/gpt-4.1":
    repair: true
    tools: ["read", "edit", "search", "bash", "write"]
    promptSectionOrder: ["tool-policy", "delivery-contract"]

Keys: exact provider/model-id or provider/*. See Per-model repair posture.

Switching providers

Set credentials for the new provider and select a model id from that catalog. Tool surface and tools.approvalMode are independent of provider id.

$ export OPENROUTER_API_KEY=...
$ veyyon --model openrouter/anthropic/claude-sonnet-4

Model selection notes

Pin models in CI and shared profiles (--model, modelRoles). Floating “latest” aliases change under you.

Where to go next

• Configuring providers: full copy-paste setups.
• Model contract: harness vs provider boundary.
• Getting started: first key and first task.
• Configuration: model defaults and overrides.
• Authentication: login, logout, secret storage.