Provider Config Reference

This page is the compact field reference for model providers. For provider setup, profile ids, aliases, custom endpoints, and operational checks, see Provider Integrations. For the model workflow, including fallback routing, see Configuring Models.

Anyy reads provider settings from config.yaml, validates unknown YAML fields strictly, then normalizes the shorthand and structured model settings into one runtime view.

Minimal Shape

providers:
  - id: openrouter
    profile: openrouter
    credential_ref: env:OPENROUTER_API_KEY
    default_model: anthropic/claude-sonnet-4

default_model: openrouter/anthropic/claude-sonnet-4
main_model:
  provider_id: openrouter
  model: anthropic/claude-sonnet-4

default_model is the provider/model shorthand. main_model is the structured form. You can write either one by hand; Anyy fills the missing form during config load when both parts are present.

Main Model Fields

Field	Type	Meaning
default_model	string	Shorthand in provider_id/model_id form. If providers are configured, the provider id must exist.
main_model.provider_id	string	Provider id used for ordinary chat and tool turns.
main_model.model	string	Model id passed to that provider.

If both forms are present, keep them consistent. The setup wizard writes both so commands, dashboard surfaces, and older config readers see the same main model.

Provider Entries

Each item under providers defines one backend connection.

Field	Type	Meaning
id	string	Required unique provider id. It is also the prefix used in default_model.
profile	string	Optional built-in profile. When omitted, Anyy can infer a profile from a known provider id.
api_mode	string	Wire protocol. Required when no profile supplies it.
auth_mode	string	Authentication mode. Defaults from the profile, or api_key without a profile.
auth_profile	string	Optional named auth choice for profiles with more than one auth path.
base_url	string	Provider endpoint. Required when no profile supplies a default.
models_url	string	Optional model-catalog endpoint. Used for listing models when supported.
credential_ref	string	Preferred credential reference. It wins over api_key_ref when both are set.
api_key_ref	string	Backward-compatible API-key reference. Use credential_ref for new config.
default_model	string	Provider-local default model shown by setup and status surfaces.
models	list	Optional manual model entries and per-model capability overrides.
aliases	map	Optional model alias map.
auxiliary_models	map	Optional provider-local aliases for auxiliary roles.
capabilities	map	Provider-wide capability overrides.
fallback_chain	list	Provider-local fallback chain.
enabled	bool	Optional switch. Omitted means the provider is enabled.

Unknown provider fields fail config validation. Keep provider ids stable once sessions or saved config refer to them.

API Modes

api_mode must be one of these values:

Value	Use
openai-compatible	OpenAI-compatible chat/completions endpoints and many hosted model routers.
anthropic-messages	Anthropic Messages-compatible endpoints.
google-gemini	Native Google Gemini API.
openai-responses	OpenAI Responses API.
codex-responses	Codex Responses backend used by the openai-codex profile.

Do not invent adapter names. For example, DeepSeek uses openai-compatible; a deepseek-compatible value is rejected.

Provider Profiles

Use Provider Integrations as the source for setup-ready profile ids, profile aliases, blocked setup entries, custom endpoint patterns, and auth-mode guidance.

This reference focuses on the YAML fields accepted after you have chosen a provider shape.

Credentials

Provider credential references use the same reference schemes as the secret system: env:NAME, file:/path/to/token, or secret:name. Literal credentials are not allowed in provider credential fields.

credential_ref is the preferred field. If both credential_ref and api_key_ref are present, Anyy uses credential_ref as the effective credential and still validates the older api_key_ref.

Auth-mode rules:

auth_mode	Credential rule
api_key	Use credential_ref or api_key_ref.
oauth	Use credential_ref when a credential reference is needed; api_key_ref is rejected.
external_process	Use credential_ref when needed; api_key_ref is rejected.
aws_sdk	Use credential_ref when needed; api_key_ref is rejected.
none	No credential refs are allowed, and the base URL must be local or private.

auth_mode: none is for local or private providers such as a local LM Studio endpoint. It is rejected for public internet endpoints.

Models

Manual model entries are optional. They are useful when a provider catalog is empty, when you want a friendly display name, or when a model needs capability overrides.

providers:
  - id: local
    profile: lmstudio
    models:
      - id: local-model
        display_name: Local Model
        capabilities:
          tool_calls: true
          streaming: true
          max_context_tokens: 32768

models[].id is the model id passed to the provider. models[].capabilities overrides or supplements provider-wide capabilities for that model.

Capability Overrides

Capabilities are exact overrides. Omit a key when you want the built-in profile or provider adapter to decide.

Boolean capability keys:

developer_messages, tool_choice_without_tools, streaming, tool_calls, json_schema, usage_metadata, multimodal_input, video_input, image_generation, reasoning_input, reasoning_output, reasoning_replay, reasoning_requires_same_provider, reasoning_requires_same_model, prompt_cache_explicit, prompt_cache_implicit, credential_refresh, credential_pool, and account_scoped_rate_limits.

Numeric and string capability keys:

Field	Meaning
max_context_tokens	Maximum model context window Anyy should assume.
max_output_tokens	Maximum output tokens Anyy should request or allow.
max_request_bytes	Request-size guardrail.
max_tool_result_chars	Tool-result budget for provider compatibility.
prompt_cache_ttl	Prompt-cache time-to-live label for providers that expose it.

Negative token or output limits are rejected during validation.

Auxiliary Models

Auxiliary model slots live at the top level, not inside a provider entry:

auxiliary_models:
  image_understanding:
    - provider_id: gemini
      model: gemini-2.5-flash
  video_understanding: []
  speech_synthesis: []
  search: []
  image_generation: []

Available slots are fallback, image_understanding, video_understanding, speech_synthesis, search, and image_generation.

Each entry accepts:

Field	Meaning
provider_id	Provider id to use for that auxiliary job.
model	Model id to pass to that provider.
enabled	Optional switch. Omitted means enabled.
extra_body	Extra request body fields for providers that support them.
allow_reasoning_drop	Allow fallback to drop reasoning continuity when needed.
allow_context_drop	Allow fallback to retry without full context when needed.
max_attempts	Per-entry retry limit.

Image and video auxiliary entries are mirrored with media_understanding.image.models and media_understanding.video.models when one side is empty, so old and new config shapes stay compatible.

Fallback Chain

The recommended setup path writes fallback models under auxiliary_models.fallback:

auxiliary_models:
  fallback:
    - provider_id: openrouter
      model: anthropic/claude-sonnet-4
      max_attempts: 1
    - provider_id: gemini
      model: gemini-2.5-pro
      allow_reasoning_drop: true

At runtime, Anyy copies this list to the main provider's effective fallback_chain when the provider does not already define one.

Provider-local fallback_chain entries use the same fields as auxiliary fallback entries. Every provider_id must reference a configured provider, and max_attempts cannot be negative.

Fallback is a resilience path, not a way to bypass capability requirements. A candidate can still be skipped if it cannot satisfy required tools, media, context, or reasoning continuity.

Validation Notes

Run anyy config after hand-editing config.yaml. It prints the resolved provider, API mode, auth reference status, model, and max-turn settings.

Use anyy doctor for a broader runtime check. Provider request failures still surface when a model is actually used; there is no separate provider health-check block in config.yaml.