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

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 public repository is not open yet, so there is no clone URL to give here. From the root of a source tree, the build is one command:

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:

./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:

./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

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.

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.