Standalone, or in a project?
A brain is the unit of publication: if somebody might want one subject without the others, those are separate brains, each publishable, installable and droppable on its own. A project is what several brains share — one actor, one retention policy, one embedder, one registry account — declared in onevitruvio.toml, with a
repository per brain derived as <namespace>/<project>-<brain>.
Choose standalone when there is one subject and you are the one writing. Choose a project when there are
several subjects you will publish separately, or several people, or you already know the brain will live beside
others. A standalone brain can join a project later — project add NAME --path PATH --no-create registers an
existing layout without touching it — so the cheaper mistake is starting standalone.
Unlike governance, this is a decision vitruvio is happy to see you change.
The actor, and who assists
Every write is attributed in provenance, so every write needs an actor: a lowercase address (you@example.com) or
a lowercase namespaced name (openai/codex). Passing --actor to brain init or project init writes it into
vitruvio.toml, and from then on it is the actor: a later --actor naming somebody else is refused, not obeyed.
Reads never need one.
Decide at the same time which agents will assist writes into the brain, and declare them with the global
--assisted-by ID flags on brain init or project add — one canonical id per agent, anthropic/claude-code,
openai/codex. They are written under assisted_by for that brain and become the only parties a write into it may
record; an agent that is not declared is refused rather than written down. A brain that declares none inherits the
project’s [[assisted_by]].
The retention policy
brain init --policy takes a retention profile: conservative (the default), permissive or archival. It decides
which removals the protocol will allow later. Unlike governance, leaving the default is fine when you have no
opinion yet, and Retention is where to form one.
Text embeddings
Choose whether this brain will use a semantic model or the default deterministic hashing/BOW index. Hashing/BOW needs no download or key, but matches words rather than synonyms. For a shared project model, declare the canonical model identity in[embedding.text] with model_id, plus provider, model, revision and dims when required.
The local runtime can be selected after creation without changing that shared declaration:
local-st loads a Sentence Transformers model into RAM when needed. Keep credentials in environment variables;
the per-brain runtime choice is saved in local XDG state without secrets.
Four recipes
The governed recipes need a fingerprint fromvitruvio auth keys; the previous page says what else to have ready.
Standalone, ungoverned
Standalone, governed
--trust-root root.toml in place of --sign-with, for distinct subjects or scopes.
The command warns when the quorum equals the number of govern holders; read it, it is telling you a lost key
would be unrecoverable.
In a project, ungoverned
project init writes the vitruvio.toml and registers the project’s name on this machine, so --project coursework
reaches it from any directory afterwards. Start in a fresh directory: if a vitruvio.toml already exists above the
working directory, project init adds the project to that file instead of creating a new one. --namespace is where the brains will publish; leave it out if you do not
know yet, and the account you log in to later is used instead. project add creates the layout at
./brains/optics and declares it.
In a project, governed
project add on its own always creates an ungoverned brain — it has no governance flags. For a governed brain
inside a project, create the genesis with brain init and then declare it with --no-create:
brain init finds the project’s vitruvio.toml and writes no second one.
Check it
brain verify passing says the bytes are intact; auth status says whether an
authorized signature supports the head. On an ungoverned brain auth status reports exactly that — ungoverned, no
trust root — and that is a description, not a failure. In a project, add --brain optics to address one brain.