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.
- The flag on the command line.
- The project's
.shoal/config.json. - 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
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
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.
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.