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 | Where models tie up: llamacpp, mlx, or remote. Left unset, Shoal detects one. |
| endpoint | An OpenAI-compatible server you run yourself. Setting this means Shoal manages no server of its own. |
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 are generated by
scripts/clidocs from Shoal 0.21.0.