Documentation
Sonny is an agentic coding engine for your terminal. It runs autonomous agent sessions against the LLM provider you choose, keeps an auditable record of every turn, and lets you scale a single chat into a distributed mesh of sessions running on machines you control.
If you are new to Sonny, start with Getting Started — it takes you from a fresh install to a working chat session in about a minute.
Start here
| If you want to… | Read this |
|---|---|
| Install the binary and run your first session | Getting Started |
| Learn every command, flag, and exit code | CLI Reference |
| Write the recipes Sonny runs on | Recipes |
| Understand durable knowledge and the control plane | Lanning |
| Run sessions on remote machines | Distributed Mesh |
| Give Sonny tools from other processes | MCP Servers |
| Use Sonny from a GUI or editor | Client Apps |
How the pieces fit together
Everything Sonny does starts from a recipe: a YAML file that names a model profile and the system prompt plus tool allowlist for a session. Recipes are covered in Recipes .
A session is one run of a recipe. Sessions are persisted to a SQLite database
under your data directory, which is what makes --continue, --session, and
the mesh transfer commands possible.
The mesh turns one session into many, scheduled across nodes: sonny mesh serve starts a node, sonny mesh push sends a session to it, and sonny mesh attach reconnects your terminal to a session that kept running without you.
MCP servers are how Sonny reaches tools that live in another process — a ticketing system, a database bridge, a packet-capture appliance. Every server must clear an operator-owned allowlist before it runs. See the trust model .
The source of truth
The CLI behaviour described in these pages matches the --help output of the
version you have installed. Where a page states a fact about a flag, a command,
or a default, the page names the source file it came from; the full mapping
lives in the source repository under docs/user/cli-reference.md.
sonny version to check what is
installed on your machine.