Choose the model an agent uses

An agent harness asks for a model by an alias, such as default, and the host decides what that alias means. So you choose the model on the host, per session or per workload, and the agent never changes or sees a key. minimal-agent and Desktop's own agents all ask for default.

Anatomy of an agent explains why the host makes every model call.

In Cosmonic Desktop

Add a model source

A model source is an endpoint Desktop can call for agents, with its key: a local Ollama, Anthropic, OpenAI, or another OpenAI-compatible service.

1. Select Models under AI & agents in the sidebar.
2. Select Add a source.
3. Choose its Kind, then fill in the Endpoint (optional for Ollama and Anthropic), an optional Default model and, for a hosted service, its API key.

The key is stored in your keychain and is never accessible to sandboxed agents. The source's default model is used when an agent or workload names no model.

Choose the model for a new session

1. On the Agents page, select New and choose the agent.
2. Select the Model chip next to the message box.
3. Choose a source in the first dropdown and a model in the second. Choose Other model… to type a model name the source does not list. Select Done.

Desktop remembers your last source, and your last model for each source, for the next session.

Switch the model in a running session

Use the Model dropdown in the session header. You can switch between runs, not while the agent is working.

What Desktop writes

Desktop records your choice on the session workload's inference entry, as the backend (the source's name) and model keys. See Agent workload reference.

On Cosmonic Control

Give the host its model sources

The operator lists model sources in the HostGroup chart under agents.models.sources. Each one has a name, a baseUrl (Control posts to <baseUrl>/chat/completions, so the endpoint must be OpenAI compatible), an optional defaultModel, an optional models allowlist, and the API key from an existing Secret:

agents:
  enabled: true
  models:
    sources:
      - name: openai
        baseUrl: https://api.openai.com/v1
        defaultModel: gpt-4.1-mini
        models: [gpt-4.1-mini, gpt-4.1]
        existingSecret:
          name: openai-api-key
          key: api-key
      - name: local
        baseUrl: http://ollama.models.svc:11434/v1
        defaultModel: qwen2.5:0.5b

The host re-reads the key on every call, so rotating the Secret needs no restart. Run an agent on Cosmonic Control shows the whole values file.

Pick a source and model in the workload

On the workload's models entry, set source to a source's name, and optionally model:

- namespace: cosmonic
  package: agent
  interfaces: [models, chat]
  version: 0.4.1
  config:
    components: agent
    source: local
    model: qwen2.5:0.5b

• source is optional when the host has exactly one source. backend is accepted as the same key.
• Without model, the source's defaultModel is used.
• max-requests and max-tokens narrow the source's limits for this workload.

A workload never supplies an endpoint or a key: keys such as base-url, endpoint, api-key and token are refused.

Give different aliases different models

An unnamed models entry answers every alias the agent opens. To send one alias somewhere else, add a models entry whose name is that alias:

- namespace: cosmonic
  package: agent
  interfaces: [models, chat]
  version: 0.4.1
  name: fast
  config:
    components: agent
    source: local

The agent opens fast and gets the local source; every other alias still goes to the unnamed entry.

Changing the source or model is a change to the workload spec, so it rolls out as a new revision. The agent's image stays the same.