---
title: "Install Shoal"
description: "Build the binary, install it as a program, and check that the machine has what it needs."
source: https://shoal.grimvane.ai/docs/terminal/install/
---

# Install Shoal

Shoal is one binary. Building it and installing it are two separate steps, and the second one is optional: a loose binary runs fine from wherever you put it. Shoal is pre-alpha.

## Shoal needs Go and something to run a model

| Piece | Needed for |
| --- | --- |
| Go 1.25 or newer | Building the binary |
| A llama.cpp release build, b8492 or newer | Local inference on Windows and Linux |
| `mlx_lm.server` on Apple Silicon | Local inference on macOS |
| A GGUF model on disk | Anything the llama.cpp dock loads |
| vLLM, or any other OpenAI-compatible server | Inference on an engine you run, on this machine or another |

The version floor is checked before every spawn. A llama-server older than b8492 is refused, because older builds carry unpatched CVEs.

Shoal looks for `llama-server` in five places, in this order:

1.  `llama-server` on PATH
2.  `~/llama.cpp/llama-server` (`.exe` on Windows)
3.  `~/llama.cpp/build/bin/llama-server` (`.exe` on Windows)
4.  `~/.local/bin/llama-server` (`.exe` on Windows)
5.  `/usr/local/bin/llama-server`

Put GGUF files in `~/llama.cpp/models/`, or in the `models` directory beside the llama-server binary. Those are the two places Shoal scans when it lists what is on this machine. `SHOAL_MODELS_DIR` replaces both with a directory of your own rather than adding to them. On Windows with an NVIDIA card, take the CUDA release zip plus the matching cudart zip and extract both into the same folder.

## You build the binary from source

The repository is currently private and will open in the future, so there is no clone URL to give here. From the root of a source tree, the build is one command:

```bash
go build -o shoal .        # use -o shoal.exe on Windows
./shoal --version
```

That produces a binary that runs on its own. Point it at a model and it starts a session:

```bash
./shoal --model ~/llama.cpp/models/gpt-oss-20b-MXFP4.gguf --dock llamacpp
```

Or point it at a server you already run, on this machine or another one:

```bash
./shoal --endpoint http://127.0.0.1:8820 --model <name>
```

## Setup turns the binary into a program

`shoal setup` installs the running binary for your user account. It copies the executable to the user programs directory, puts `shoal` on PATH so any new terminal runs it by name, and registers it with the operating system. On Windows that means `%LOCALAPPDATA%\Programs\Shoal`, an entry on the user PATH, two Start Menu entries, and a row in Apps and features. On Linux and macOS the binary lands in `~/.local/bin`, and setup tells you when that directory is not on your PATH. Nothing asks for elevation on any platform.

Re-running setup from a newer binary upgrades the install in place. If no default model is saved yet and a terminal is attached, setup also asks which model to use, so the first launch afterwards lands in a working session.

`shoal setup --uninstall` reverses every one of those steps. Session data and config are kept.

## Doctor reports what the machine has

```bash
shoal doctor
```

Doctor prints the platform it detected (OS, architecture, GPU, RAM, and VRAM), each dependency check marked ok or failed, the models on disk with whether each one’s chat template can carry a tool call, the inference servers answering locally and on which ports, and the state of any configured hooks and their secret references. Reading a model’s tool-call support comes from the GGUF header, so no weights load. Failed checks are counted at the end.

`shoal models` covers the same ground for models alone: sizes, tool-call support, which one fits the memory budget, and the command that moors it.

## A saved default makes a bare shoal work

Launch settings resolve in three places, and the first one that answers wins: a command-line flag, then the project’s `.shoal/config.json`, then the user-wide defaults.

```bash
shoal config set model gpt-oss-20b-MXFP4.gguf
shoal config                    # current defaults and the file holding them
shoal config unset model
```

The keys are `model`, `dock` (`mlx`, `llamacpp`, or `remote`), and `endpoint`. Once a default model is saved, a bare `shoal` in any directory is enough.