Configuring Models

Anyy runs on configurable model backends. You choose which provider and model power the assistant; Anyy itself always identifies as Anyy, and a provider or model name is only a backend label — never the assistant's identity.

This page is the model-configuration workflow: how to set the main model that answers everyday requests, how to enable optional auxiliary capabilities (image, video, image generation, speech), and how to set up a fallback chain so a transient provider failure can route to another model.

Three distinct concepts, configured by three distinct commands, are kept separate throughout this page:

Concept	What it does	Config location	Command
Main model	Answers ordinary chat and tool turns	main_model / default_model	anyy setup model
Auxiliary capabilities	Optional media skills (image/video/imagegen/tts/stt)	auxiliary_models.*, media_understanding, tts, media_generation	anyy setup aux
Fallback chain	Backup models for the main model on provider error	auxiliary_models.fallback	anyy setup model fallback

This page owns the workflow. For background:

• For credential storage and provider sign-in, see Credentials & Authentication.
• For the exhaustive list of provider and model config fields, see the Provider Config Reference.
• To configure everything at once on first run, use the Setup wizard.

Models Page

Two read-only surfaces show your current model configuration without changing it.

Run anyy config to print the resolved configuration for the active home. The Model section reports the default model, its provider, the base URL, the API mode, and how the provider authenticates:

◆ Model
  Default model    example-provider/example-model
  Provider         example-provider
  Base URL         https://api.example.com/v1
  API mode         openai-compatible
  Auth             env:EXAMPLE_API_KEY (not set)
  Max turns        90

The anyy config view is read-only — it never edits the file. Use the setup commands below to make changes.

When the resident gateway is running, the dashboard's Models page renders the same information as cards: the main model, any fallback entries, and each configured auxiliary capability (image understanding, video understanding, image generation, text-to-speech, speech-to-text), grouped by category. From there you can also set the main model (saved globally), reconfigure a provider (its API key, base URL, and model), and test a connection — mirroring the setup model flow.

Set The Main Model

The main model answers ordinary chat and tool-using turns. Configure it with:

anyy setup model

anyy setup model

Configure provider, auth, and default model.

Usage:
  anyy setup model [--home PATH]
  anyy setup model fallback [--home PATH]

The wizard walks three steps:

1. Select provider. Pick from the built-in provider templates. The one matching your current configuration is marked currently active.
2. Authenticate. Depending on the provider, enter an API key (stored as a profile-local secret file, with only a reference written to config.yaml) or complete a provider sign-in flow. Credential handling is covered in Credentials & Authentication.
3. Choose the model. The wizard loads the provider's model catalog and lets you pick an entry, or choose Enter model id to type one manually when the catalog is empty or your model is not listed.

setup model requires an interactive terminal — provider authentication and model selection are interactive prompts:

✗ Setup model needs an interactive terminal

Reason:
  provider authentication and model selection require interactive prompts

Next:
  run anyy setup model from an interactive terminal

On confirmation, the wizard writes both forms of the main-model setting so they stay in sync:

default_model: example-provider/example-model   # "provider/model" shorthand
main_model:
  provider_id: example-provider
  model: example-model

You only need to set one of default_model or main_model by hand — Anyy normalizes one from the other on load. default_model is the provider/model shorthand; main_model is the structured form.

Flag placement

Command flags go after the subcommand: anyy setup model --home PATH, not anyy --home PATH setup model. The leading --home/--socket/--resume flags are reserved for the default entrypoint.

Set Auxiliary Models

Auxiliary capabilities are optional model roles for media that the main model may not handle. They are configured separately from the main model and stored under auxiliary_models.* (and the related media_understanding, tts, and media_generation sections).

anyy setup aux

anyy setup aux

Configure optional model capabilities.

Usage:
  anyy setup aux [--home PATH] [--probe]
  anyy setup aux CAP [--home PATH] [--probe]

Capabilities:
  image    image understanding
  video    video understanding
  imagegen image generation
  tts      text-to-speech
  stt      speech-to-text
  search   web search (coming soon)

Running anyy setup aux with no capability opens a multi-select menu of all capabilities; already-configured ones are pre-checked. Pass a specific CAP to jump straight to one capability, for example anyy setup aux image or anyy setup aux tts. search is listed but marked coming soon and cannot be configured yet.

For each capability the wizard asks which connection to use. You can:

• Reuse an existing provider you already configured (including the main model's connection), or
• choose + Add a new connection to enter a separate base URL and key, or
• Skip / keep current to leave it unchanged.

Capabilities that support a connection test accept --probe to verify the binding during setup (currently imagegen and tts).

Common override patterns

A capability that you do not configure simply inherits the main model where the main model can handle that media. The setup aux menu shows this as the hint inherits main: <provider/model>. Configure a capability explicitly only when you want a different model for that media type than your main model — for example, a dedicated vision model for image understanding while keeping a text-focused main model.

Single task override

To change exactly one capability without touching the others, pass its key directly:

anyy setup aux image      # only image understanding
anyy setup aux tts        # only text-to-speech
anyy setup aux imagegen --probe   # configure image generation and test it

This opens just that capability's prompts; every other role is left as-is.

Reset to automatic routing

To stop using a dedicated auxiliary model and fall back to the main model's automatic routing, clear that capability's entry in config.yaml. For example, removing the image_understanding list under auxiliary_models (and the matching media_understanding.image.models) returns image handling to the main model. After editing, run anyy config to confirm the capability no longer shows a dedicated model.

Provider Authentication

Each provider is authenticated independently. The main model's provider, every auxiliary connection, and every fallback provider can each carry their own credential. Two authentication shapes exist:

• API key — entered in the wizard, stored as a profile-local secret file, and referenced from config.yaml (for example api_key_ref: env:EXAMPLE_API_KEY or a file:/secret: reference). The key value never lands in config.yaml.
• Provider sign-in — for providers that offer an account login instead of a raw key, the wizard runs the sign-in flow and records the resulting credential.

anyy config reports each provider's credential status (for example env:EXAMPLE_API_KEY (not set) when a referenced environment variable is missing), so you can tell at a glance which providers are ready.

The full credential model — reference schemes, where secrets live on disk, sign-in flows, and redaction — is documented in Credentials & Authentication.

Model Routing

At runtime Anyy resolves a request to a concrete model in this order:

1. Main model handles the request by default.
2. If a request needs a capability bound to an auxiliary model (such as image or video understanding), that media is routed to the configured auxiliary model for the role; otherwise it stays on the main model.
3. If the main model's provider returns a retryable provider error that signals a fallback, routing moves down the fallback chain (next section).

You can also switch the active model on the fly without rerunning setup. In the TUI, the model picker can pin a model to the current session; the dashboard's Models page saves the main model globally. Both paths target the same provider/model shape you would otherwise set with setup model.

Fallback Routing

A fallback chain lets a transient main-model failure route to another model instead of surfacing an error. It is configured against the main model and stored under auxiliary_models.fallback:

anyy setup model fallback

anyy setup model fallback

Configure fallback routing for the main model.

Usage:
  anyy setup model fallback [--home PATH]

Fallback setup requires a main model to already be configured — it has to have an owner. If none is set, the wizard tells you to run anyy setup model first.

The editor offers three actions:

• Keep current fallback routing — leave the chain unchanged.
• Replace fallback routing — build a new ordered chain. The wizard lists your configured providers that have a default model; pick them in priority order and confirm Add another fallback provider? to extend the chain.
• Clear fallback routing — remove the auxiliary fallback entirely.

A resulting chain looks like this in config.yaml:

auxiliary_models:
  fallback:
    - provider_id: backup-provider
      model: backup-model
      max_attempts: 1

Fallback only engages on a fallback-eligible provider error, and Anyy picks the first compatible candidate in order. A candidate is skipped when it cannot meet the in-flight request's needs — for example, it lacks tool-calling when tools are in use, lacks image or video input when the turn carries that media, or has a smaller context window than the current model. Two opt-in flags relax the last two checks per entry:

Field	Effect
allow_context_drop	Permit a fallback model with a smaller context window
allow_reasoning_drop	Permit a fallback model that cannot replay prior reasoning
max_attempts	Attempts against this entry before moving on

These per-entry fields are documented in full in the Provider Config Reference.

Capability Cache

When Anyy needs to know whether a model supports image or video input (for example, to decide whether a fallback candidate is compatible), it records what it learns in a model capability cache at <home>/cache/model_capabilities.json. The cache is keyed by provider, model, and base URL, so probing the same model again is cheap.

The cache is an optimization, not configuration — you do not edit it by hand. If a provider's capabilities change, deleting the file simply forces Anyy to relearn them on next use.

When Changes Take Effect

The setup commands write nothing until you reach the final confirmation; canceling leaves your configuration untouched. After a confirmed write, configuration is re-read by the runtime — when the resident gateway is running, model and provider changes apply to subsequent requests without a manual restart, and the dashboard's Models page reflects the new state. A session that has already pinned a model via the TUI model picker keeps that model until the session ends or you switch again.

Run anyy config at any time to confirm the resolved main model, provider, and auth status.

Troubleshooting

• "Setup model needs an interactive terminal." setup model requires real prompts. Run it from an interactive terminal, not a pipe or non-interactive script.
• "Default TUI flag used with a command." You put --home (or --socket / --resume) before the subcommand. Move command flags after the command: anyy setup model --home PATH.
• Fallback setup refuses to run. It requires a configured main model first; run anyy setup model, then anyy setup model fallback.
• A fallback never triggers. Fallback only engages on a fallback-eligible provider error and only to a compatible candidate. If the backup model has a smaller context window or lacks tool / image / video support the turn needs, it is skipped; set allow_context_drop or allow_reasoning_drop on that entry if the drop is acceptable.
• Auth shows "(not set)". The provider's referenced credential (for example an environment variable) is missing. Re-run anyy setup model to re-enter it, or provide the referenced secret. See Credentials & Authentication.
• An auxiliary capability is ignored. Confirm it is configured with anyy config; an unconfigured capability falls back to the main model, and search is not available yet.