Auth rules

Local and LAN hosts 
Loopback, private-network, `.local`, and bare-hostname Ollama URLs do not need a real bearer token. Apus uses the `ollama-local` marker for these.
Remote and Ollama Cloud hosts 
Public remote hosts and `https://ollama.com` require a real credential: `OLLAMA_API_KEY`, an auth profile, or the provider's `apiKey`. For direct hosted use, prefer the `ollama-cloud` provider.
Custom provider ids 
A custom provider with `api: "ollama"` follows the same rules. For example, an `ollama-remote` provider pointed at a private LAN host can use `apiKey: "ollama-local"`; sub-agents resolve that marker through the Ollama provider hook instead of treating it as a missing credential. `memory.search.provider` can also point at a custom provider id so embeddings use that Ollama endpoint.
Auth profiles 
SQLite auth stores hold the credential for a provider id; put endpoint settings (`baseUrl`, `api`, models, headers, timeouts) in `models.providers.<id>`. Older flat `auth-profiles.json` files such as `{ "ollama-windows": { "apiKey": "ollama-local" } }` are not a runtime format; `apus doctor --fix` imports them into SQLite as a canonical `ollama-windows:default` API-key profile with a backup. A `baseUrl` value in that legacy file is noise and should move to provider config.
Memory embedding scope 
Bearer auth for Ollama memory embeddings is scoped to the host it was declared for:

- A provider-level key is sent only to that provider's host.
- `memory.search.remote.apiKey` and per-agent overrides are sent only to their remote embedding host.
- A pure `OLLAMA_API_KEY` env value is treated as the Ollama Cloud convention and is not sent to local/self-hosted hosts by default.

Getting started

Onboarding (recommended)

Run onboarding

    ```bash
    apus onboard
    ```

    Select **Ollama**, then pick a mode: **Cloud + Local** or **Local only**. For hosted models without a local Ollama host, choose **Ollama Cloud** instead.

    On a fresh guided setup, Apus first checks the default or configured
    Ollama host. Automatic discovery considers only models already loaded in
    memory, as reported by `/api/ps`, with tool support and at least 16K of
    context confirmed by `/api/show`. An eligible model installed on disk but
    not loaded is not an automatic candidate. The selected route still needs
    a real completion before Apus saves it; discovery never pulls or
    loads an idle model.

    To use an installed but idle model in desktop Model Setup, choose
    **Choose connection** on the Ollama card, then **Local only**. This
    explicit setup path can prepare an eligible installed model for the live
    check without requiring it to be loaded already.

Select a model

    `Cloud + Local` and `Local only` prompt for an Ollama base URL and inspect installed models; an `ollama.com` URL is rejected there because hosted access belongs to **Ollama Cloud**. If no tools-capable model is found, setup can ask permission to pull a recommended model. An installed `:latest` tag such as `gemma4:latest` is shown once instead of duplicating `gemma4`. `Cloud + Local` also checks whether the host is signed in for cloud access.

Verify

    ```bash
    apus models list --provider ollama
    ```

Non-interactive:

```bash
apus onboard --non-interactive --accept-risk --skip-health \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b"
```

`--custom-base-url` and `--custom-model-id` are optional; omitting them uses the local default host and the `gemma4` suggested model.

A local model advertised as embedding-only cannot be selected as the chat
default. Setup reports an error and leaves the existing configuration intact;
reset preflight also rejects an explicitly selected embedding-only model or
an inventory advertised as entirely embedding-only. Models that support both
completion and embeddings remain eligible.

Manual setup

Install and start Ollama

    Get it from [ollama.com/download](https://ollama.com/download), then pull a model:

    ```bash
    ollama pull gemma4
    ```

    For hybrid cloud access, run `ollama signin` on the same host.

Set a credential

    For a local or LAN host, any value works:

    ```bash
    export OLLAMA_API_KEY="ollama-local"
    ```

    For `https://ollama.com`, use the real key instead:

    ```bash
    export OLLAMA_API_KEY="your-real-key"
    ```

    Or in config: `apus config set models.providers.ollama.apiKey "OLLAMA_API_KEY"`.

Select the model

    ```bash
    apus models list
    apus models set ollama/gemma4
    ```

    Or in config:

    ```json5
    {
      agents: {
        defaults: {
          model: { primary: "ollama/gemma4" },
        },
      },
    }
    ```

Cloud models through a local host

Cloud + Local routes both local and :cloud models through one reachable Ollama host — this is Ollama's hybrid flow and the mode to pick during setup when you want both.

Apus prompts for the base URL, discovers local models, and checks ollama signin status. When signed in, it suggests hosted defaults (minimax-m2.7:cloud, minimax-m3:cloud, kimi-k3:cloud, glm-5.1:cloud, glm-5.2:cloud). If not signed in, setup stays local-only until you run ollama signin.

For cloud-only access without a local daemon, use apus onboard --auth-choice ollama-cloud and see Ollama Cloud — that path does not need ollama signin or a running server:

apus onboard --auth-choice ollama-cloud
apus models set ollama-cloud/minimax-m2.7:cloud

The Ollama Cloud model list comes from live https://ollama.com/api/tags discovery with your key, so the picker reflects the current hosted catalog. Without a usable key, Apus shows its bundled Ollama Cloud catalog.