# Setup

This repo is a guide (`README.md`) plus two small helper scripts. There is nothing to build or compile here — the "install" is the actual local AI stack the README walks you through (Ollama, optionally LM Studio, optionally the voice tools). This SETUP.md tells you what you need before you start and gets you through the first, mandatory step (Ollama + your first model). Everything after that is optional and is covered in `README.md` itself, in order — read it top to bottom.

## What you need

| Requirement | Why | Have it already? |
|---|---|---|
| A Mac with Apple Silicon (M1/M2/M3/M4) | The main README path (Sections 1-4) targets Apple Silicon, including Metal-accelerated voice tools. Intel Mac / Windows / Linux users: skip to `docs/windows-linux.md` — Sections 1, 2, and 5 work identically, only install commands and the voice stack differ. | Check: Apple menu > About This Mac > chip |
| 8 GB+ unified memory (16 GB+ recommended, 32 GB+ for larger models) | Local models run in RAM; undersized RAM means swapping or the model won't load. | Check: Apple menu > About This Mac > memory |
| 5-40 GB free disk space | Model weight files are large (a few hundred MB to several GB each). | Check: `df -h /` |
| Homebrew (macOS package manager) | Used to install Ollama and whisper.cpp with one command each. | Check: `brew --version` |
| Terminal comfort (copy-paste commands, one at a time) | Every step below is a shell command. | — |
| Docker | NOT needed. Nothing in this repo runs in a container. | — |
| A cloud account or API key (OpenAI, Anthropic, etc.) | NOT needed. The entire point of this guide is running models with no account and no API key. | — |
| A paid subscription of any kind | NOT needed. Ollama, LM Studio, whisper.cpp, and mlx-audio are all free and open-weight/open-source. | — |
| A dedicated/discrete GPU | NOT needed. Apple Silicon's built-in GPU (via Metal) is used automatically — there is nothing to configure. | — |

## Install, step by step

These steps cover the mandatory core: a working Homebrew, then Ollama, then your first model. LM Studio (README Section 3), the voice stack (README Section 4), and wiring into agent tools (README Section 5) are optional add-ons — once you finish step 3 below, go read those sections in `README.md` in order and follow the commands there.

### 1. Install Homebrew (skip if `brew --version` already prints something)

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
This installs macOS's standard package manager, which the next step uses.

Check it worked:
```bash
brew --version
```
Expected: a line like `Homebrew 4.x.x`.

Windows/Linux: skip this step and Homebrew entirely — go to `docs/windows-linux.md` and use the Ollama installer/script shown there instead, then return to step 3 below.

### 2. Install Ollama and start it

```bash
bash scripts/install-mac.sh
```
This runs `brew install ollama`, then starts the Ollama background service (`ollama serve`). You can also just run `brew install ollama` yourself if you prefer to see each step.

Check it worked:
```bash
curl -s http://localhost:11434
```
Expected: `Ollama is running`.

### 3. Pull your first model

```bash
bash scripts/pull-models.sh
```
This downloads the two starter models listed at the top of the script (`llama3.2` and `qwen2.5-coder`) — edit that file first if you want different models or sizes (see README.md Section 2 for sizing your model to your RAM).

Check it worked:
```bash
ollama list
```
Expected: a table showing `llama3.2` (and `qwen2.5-coder`) with a size and modified date.

At this point the mandatory setup is done. For the GUI app, local voice (speech-to-text / text-to-speech), and wiring a local model into agent tools like Claude Code, follow `README.md` Sections 3 through 6 in order — each has its own copy-paste commands.

## Configure

Nothing to configure to chat with a local model — Sections 1-4 of the README need no environment variables or config files.

Only if you get to README Section 5 (wiring a local model into scripts or agent frameworks): copy `config.example.env` to `.env` and adjust if needed.

```bash
cp config.example.env .env
```

`.env` contents (the `YOUR_KEY_HERE` lines are harmless placeholders — a local Ollama/LM Studio server does not check them against anything real):

```
LOCAL_AI_BASE_URL=http://localhost:11434/v1   # keyzhub-allow
LOCAL_AI_API_KEY=YOUR_KEY_HERE                 # keyzhub-allow
LOCAL_AI_MODEL=llama3.2                        # keyzhub-allow
```

`.env` is already in `.gitignore` — it will not get committed even though it's not a secret in this case.

## Run it

```bash
ollama run llama3.2
```

Success looks like an interactive prompt (`>>>`) where you can type a message and get a reply streamed back in your terminal, entirely offline. Type `/bye` to exit.

## Troubleshooting

1. **`brew: command not found`** — Homebrew isn't installed or isn't on your PATH yet. Run the install command in step 1 above, then close and reopen your terminal (Homebrew's installer prints an extra "next steps" command on Apple Silicon to add it to your PATH — run that too if shown).

2. **`curl: (7) Failed to connect to localhost port 11434` / `ollama: command not found`** — Ollama isn't installed or isn't running. Run `bash scripts/install-mac.sh`, or if it's installed but not running, run `ollama serve` in a terminal window and leave it open (or just open the Ollama menu-bar app if you installed via the `.dmg`, which starts the service for you).

3. **`pull-models.sh` or `ollama run` hangs or the model never finishes downloading** — usually a slow connection on a multi-GB file, not a real error; let it run. If it fails outright, check free disk space with `df -h /` — model pulls fail silently-ish when the disk is full.