> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whatsy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How to install and configure Ollama for Whatsy on macOS

> Install Ollama on macOS, download the llama3.2 model, and verify Whatsy can connect to the local LLM before enabling auto-replies.

Whatsy generates all replies locally using [Ollama](https://ollama.com) — a runtime that lets you run large language models on your own Mac without sending any data to a cloud service. Your messages, persona instructions, and conversation history never leave your machine. Before Whatsy can send a single auto-reply, Ollama must be installed, running, and loaded with a compatible model. This page walks you through every step, with troubleshooting guidance for the most common problems.

<Warning>
  Whatsy will not generate replies if Ollama is unreachable. The auto-reply toggle will appear active in Settings, but no messages will be sent until the connection to Ollama is restored.
</Warning>

## Getting Ollama working

<Steps>
  <Step title="Install Ollama">
    Download and install Ollama for macOS from [ollama.com](https://ollama.com). You can install it in two ways:

    **Option A — Ollama app (recommended):** Download the `.dmg` from the website, open it, and drag Ollama to your Applications folder. Launch it from Applications — you will see the Ollama llama icon appear in your menu bar.

    **Option B — Homebrew:**

    ```bash theme={null}
    brew install ollama
    ```
  </Step>

  <Step title="Start the Ollama server">
    If you installed the Ollama app, it starts the server automatically when you launch it. If you installed via Homebrew or need to start it manually, run:

    ```bash theme={null}
    ollama serve
    ```

    Leave this Terminal window open, or configure Ollama to run at login so you do not need to think about it (see the tip at the bottom of this page).
  </Step>

  <Step title="Pull the recommended model">
    Whatsy defaults to `llama3.2`. Pull it now:

    ```bash theme={null}
    ollama pull llama3.2
    ```

    The download is roughly 2 GB. Progress is shown in the terminal. Once complete, the model is stored locally and available immediately.
  </Step>

  <Step title="Verify Ollama is running">
    Confirm the server is up and your model is registered:

    ```bash theme={null}
    curl http://localhost:11434/api/tags
    ```

    You should receive a JSON response listing your installed models:

    ```json theme={null}
    {
      "models": [
        {
          "name": "llama3.2:latest",
          "model": "llama3.2:latest",
          "modified_at": "2025-01-01T00:00:00Z",
          "size": 2019393189
        }
      ]
    }
    ```

    If you see `llama3.2` in the list, you are ready. If the request is refused or times out, go back to Step 2 and make sure `ollama serve` is running.
  </Step>

  <Step title="Open Whatsy">
    Launch Whatsy. The onboarding screen automatically checks Ollama every two seconds. When Ollama is reachable and `llama3.2` is installed, the status indicator turns green and the **Next** button becomes active. You do not need to configure anything manually — Whatsy detects the connection on its own.
  </Step>
</Steps>

## Choosing a model

Whatsy works with any model installed in Ollama, and you can switch models at any time from **Settings → AI Model** without restarting the agent.

| Model         | Speed    | Quality | Best for                         |
| ------------- | -------- | ------- | -------------------------------- |
| `llama3.2`    | Fast     | Good    | Most Macs, everyday use          |
| `llama3.1:8b` | Moderate | Better  | 16 GB+ RAM, more nuanced replies |

**`llama3.2` is the recommended starting point.** It runs well on modern Macs with 8 GB of unified memory and produces natural, context-aware replies for most use cases.

**`llama3.1:8b`** produces more nuanced and stylistically accurate replies but requires more memory and takes longer to generate each response. Pull it the same way:

```bash theme={null}
ollama pull llama3.1:8b
```

<Tip>
  To make Ollama start automatically when you log in, open the Ollama app, click the llama icon in your menu bar, and enable **Start at Login** in Preferences. This way Whatsy always has a running Ollama server without any manual steps.
</Tip>

## Troubleshooting

### Ollama is not reachable

If Whatsy or your `curl` test cannot connect to Ollama, work through these checks:

**Make sure Ollama is running.** Look for the llama icon in your macOS menu bar. If it is not there, open the Ollama app from Applications or run `ollama serve` in Terminal.

**Do not change the default URL.** Whatsy connects to `http://localhost:11434` by default, which is where Ollama always listens. Only change this if you intentionally moved Ollama to a different host or port, which is uncommon.

**Check for firewall or VPN interference.** Some corporate VPNs or third-party firewalls block `localhost` connections. Temporarily disable your VPN or firewall and try again. If that resolves the issue, add an exception for `127.0.0.1:11434` in your VPN or firewall settings.

### Model not found

If Ollama is running but Whatsy reports that `llama3.2` is not available, check what you actually have installed:

```bash theme={null}
ollama list
```

If `llama3.2` is absent from the list, pull it:

```bash theme={null}
ollama pull llama3.2
```

If you see a model with a similar name (for example `llama3.2:3b` or `llama3:latest`), that is a different model. Whatsy looks specifically for a name that contains `llama3.2`, so pulling the exact model name as shown above is the safest approach.

### Onboarding screen stays on "checking Ollama…"

Whatsy polls `http://localhost:11434/api/tags` every two seconds. If the screen never advances past the spinner, Ollama is not responding. Confirm the server is running with `ollama serve`, then wait up to five seconds for the next poll. If it still does not resolve, force-quit Whatsy, restart Ollama, and reopen the app.