Cerveau
A local-first agentic coding harness, built from scratch for small models on the machine you already own. This documents every part of it: how to run it, how it is put together, and how to work on it.
Cerveau is a Go core with an embedded Svelte panel, shipped as one binary bound to 127.0.0.1. It drives a model you serve yourself over an OpenAI-compatible URL, keeps its memory in Typesense on your disk, and never makes an outbound call. No accounts, no telemetry, no cloud.
Where to start
The shape of it
Five subsystems do the work. Each one exists because a small model fails in a specific way, and each is a compiled mechanism rather than an instruction the model can talk itself out of.
| Subsystem | What it solves | Read |
|---|---|---|
| Memory | A model that forgets between turns, and summaries that lose the original. | Memory |
| Context window | A 96K budget spent badly, and history that vanishes without a trace. | Context window |
| Safety guard | A model talked into rm -rf / by a prompt. | Safety guard |
| Tool registry | Tools that a mode should not be able to reach, and failures worth retrying. | Tools |
| Brain Cores | Being locked to one inference engine. | Brain Cores |
Conventions in these docs
Paths are relative to the repository root unless stated otherwise. Where a page cites a default, it is the value in the source, not an idealised one — the file is named so you can check it. Ports are the shipped defaults and every one of them is configurable.
| Written as | Means |
|---|---|
~/.crv/ | Per-user state: sessions, models, the pairing id. |
~/.config/cerveau/config.json | The config file the core actually reads. |
| safe | A tool with no side effects outside a read. |
| sensitive | A tool that writes, and is mode-fenced. |
| dangerous | A tool that runs arbitrary commands. Autopilot only. |