---
title: "Configuration"
description: "The settings that make a bare shoal complete, and the order they are read in."
source: https://shoal.grimvane.ai/docs/reference/configuration/
---

# Configuration

## What wins

Shoal resolves each launch setting in one order and stops at the first answer it finds. A flag you typed beats a project's settings, and a project's settings beat your user-wide defaults. That is what lets one repository pin a model without changing what every other repository does.

1.  The flag on the command line.
2.  The project's `.shoal/config.json`.
3.  Your user-wide defaults, set with `shoal config set`.

When every source misses, Shoal starts unmoored rather than guessing. No dock is detected, no server starts, and the agent refuses every call with a message telling you to pick a model. The session, the fleet, and the mooring form all still work, so choosing one from inside a running session is the ordinary fix.

## User-wide defaults

`shoal config` shows the current defaults and the file they are kept in. `shoal config set <key> <value>` writes one, and `shoal config unset <key>` clears it. There are three keys.

| Key | What it decides |
| --- | --- |
| `model` | The model a bare shoal starts on. Set this and you stop typing --model. |
| `dock` | One of llamacpp, mlx, or remote. Left unset, Shoal detects one. Any OpenAI-compatible server Shoal did not start is remote, whether it is vLLM on this machine, llama-server on another, or a vendor behind a key. The anthropic and openai docks are reached through a mooring record. |
| `endpoint` | An OpenAI-compatible server you name, on this machine, on the LAN, on a rented GPU, or at a vendor such as OpenAI or OpenRouter. Set it and Shoal moors there instead of starting a server of its own. |
| `breakwater` | See shoal config for what this key accepts. |
| `trust` | See shoal config for what this key accepts. |
| `rowlog` | See shoal config for what this key accepts. |
| `memory` | See shoal config for what this key accepts. |
| `voyage` | See shoal config for what this key accepts. |

## Project settings

A repository can carry its own `.shoal/config.json`. It takes the same launch keys, plus the test command Bosun runs to check a decomposition conserved behaviour, and the moorings this project should know about. Nothing here is required to get started. A machine with no project file behaves exactly as it did before the file existed.

## Editor settings

> **For the VS Code extension.**
>
> The extension reads two settings, both of them machine scope. That scope is the point: a repository you opened cannot redirect which executable runs or add flags to it, so cloning an untrusted project cannot turn your approvals off.
>
> ### shoal.command
>
> The shoal binary. The default expects shoal setup to have put it on PATH. Machine scope: a workspace's settings can never redirect the executable.
>
> string, default `"shoal"` , machine scope
>
> ### shoal.extraArgs
>
> Extra flags passed to \`shoal proto\` (for example --model or --endpoint). Defaults come from shoal config. Machine scope: a workspace's settings can never inject flags like --auto-approve.
>
> array, default `[]` , machine scope

> **For the terminal.**
>
> The VS Code extension adds two settings of its own. Switch this page to VS Code at the top of the sidebar to see them.

> **For the desktop app.**
>
> The VS Code extension adds two settings of its own. Switch this page to VS Code at the top of the sidebar to see them.

## Where things are kept

| Path | What is in it |
| --- | --- |
| `.shoal/config.json` | This project's settings, moorings, and test command. |
| `.shoal/chart.yaml` | The map of this project. Hand-editable on purpose, and rebuilt with `shoal --index`. |
| `.shoal/hooks.json` | Outside tools this project binds in. A user-wide file at `~/.shoal/hooks.json` holds the ones every project gets. |
| `~/.shoal/secrets.json` | Credentials a hook authenticates with, owner-only on disk, managed by `shoal secret`. Values are never printed and are redacted out of anything a model could see. |

The key list and the editor settings match Shoal 0.32.0.