# Vitruvio

> The runtime for a Boltzmann brain: portable, verifiable, model-agnostic knowledge that any model can read and none of them owns.

- [Introduction](https://vitruvio.sh/docs/index.md): Vitruvio is the runtime for a Boltzmann brain: portable, verifiable, model-agnostic knowledge that any model can read and none of them owns.
- [Install](https://vitruvio.sh/docs/get-started/install.md): One command installs vitruvio into an isolated environment. Then check the version, pick extras, and keep it current.
- [Skills for your agent](https://vitruvio.sh/docs/get-started/skills.md): Install the skills that teach an agent how to drive vitruvio: npx skills add getsfumato/vitruvio, or vitruvio skills install.
- [Your first brain](https://vitruvio.sh/docs/onboarding/index.md): From an installed vitruvio to a working brain: two decisions that cannot be changed later, one command, and the checks that tell you it worked.
- [Governed or ungoverned](https://vitruvio.sh/docs/onboarding/governed-or-ungoverned.md): The first decision, and the one you cannot revisit: whether a trust root names the keys whose signatures consumers may accept.
- [Create a brain](https://vitruvio.sh/docs/onboarding/create-a-brain.md): Standalone or inside a project, then one of four recipes, then two checks read separately.
- [First evidence and search](https://vitruvio.sh/docs/onboarding/first-evidence-and-search.md): Register one file, build the indices, run one search, and read what came back as evidence rather than as an answer.
- [What is a Boltzmann brain](https://vitruvio.sh/docs/concepts/what-is-a-boltzmann-brain.md): The protocol vitruvio runs: typed, content-addressed blocks in five memory modules, a Merkle DAG per module, and a brain that returns evidence rather than prose.
- [How vitruvio runs a brain](https://vitruvio.sh/docs/concepts/how-vitruvio-runs-a-brain.md): The lifecycle of a brain in commands, the one output contract every command honours, the exit codes, and why every write names an actor.
- [Searching](https://vitruvio.sh/docs/brain/searching.md): Filters versus hints, and reading a bundle without over-claiming.
- [Counting with SQL](https://vitruvio.sh/docs/brain/sql.md): How many, grouped how, satisfying what: exact answers over every accessible block.
- [Browsing](https://vitruvio.sh/docs/brain/browsing.md): Reading and querying in the terminal interface, and what its views can show.
- [Ingest: the agent-as-proposer loop](https://vitruvio.sh/docs/brain/ingest.md): The propose → validate → commit loop, and the four rules a proposal fails on.
- [Retention: five ways to remove something](https://vitruvio.sh/docs/brain/retention.md): Five removal mechanisms, and which one you actually want.
- [Publishing and installing](https://vitruvio.sh/docs/brain/publishing.md): OCI artifacts, credentials, and the Docker traps.
- [Migrating legacy brains](https://vitruvio.sh/docs/brain/migrating-legacy-brains.md): The temporary compatibility command, dry runs, backups, identity preservation and the boundaries of a one-way migration.
- [Registering evidence](https://vitruvio.sh/docs/sources/registering-evidence.md): Media types, normalized views, and why images have no pipeline.
- [Declared sources](https://vitruvio.sh/docs/sources/declared-sources.md): Declaring where material comes from, pulling only what is new, and why a pull cannot resurrect redacted bytes.
- [Writing a source kind](https://vitruvio.sh/docs/sources/writing-a-source-kind.md): Sources are plugins: what the configuration may name, what a kind must implement, and how to scaffold one.
- [Projects](https://vitruvio.sh/docs/projects/index.md): One project, many brains: what they share, how each is named, and where each one publishes.
- [Selecting a brain](https://vitruvio.sh/docs/projects/selecting-a-brain.md): By name, by project, from anywhere: the resolution order, and why there is no machine-wide active brain.
- [Publishing a project](https://vitruvio.sh/docs/projects/publishing-a-project.md): Log in once, derive one repository per brain, push them all, and declare the brains you must never republish.
- [Behind, ahead, or diverged](https://vitruvio.sh/docs/reconciliation/behind-ahead-diverged.md): Local and remote disagree. Three of the four situations have a one-command answer that is safe; the fourth is a reconciliation. Find out which one you are in before writing anything.
- [Joining two histories](https://vitruvio.sh/docs/reconciliation/joining-two-histories.md): Joining a history somebody else advanced: why the three strategies land the same blocks, and what each one costs in attribution.
- [Branches: a tag per line of work](https://vitruvio.sh/docs/reconciliation/branches.md): When several people publish one brain, a shared tag makes every push after the first exit 8. A branch publishes to a tag of its own, so nobody refuses anybody, and the joining is one deliberate merge.
- [Signing and trust roots](https://vitruvio.sh/docs/authenticity/signing-and-trust-roots.md): Integrity versus authenticity, a governed genesis, explicit signing, and rotating or revoking keys.
- [Pinning and verifying](https://vitruvio.sh/docs/authenticity/pinning-and-verifying.md): What a consumer does: pin a trust root, let installation be gated, and audit authorship and history.
- [Compound: one question, several brains](https://vitruvio.sh/docs/compound/searching-several-brains.md): One question across several brains of one project: why the result is grouped by default, what --fuse does, and what a block two brains hold means.
- [The catalog](https://vitruvio.sh/docs/catalog/classifying-evidence.md): Portable metadata over canonical evidence: schemes, classes, hierarchy, placements and filtered retrieval.
- [Indices](https://vitruvio.sh/docs/under-the-hood/indices.md): The six kinds, what each tells the planner, and why an empty index is worse than none.
- [The query planner](https://vitruvio.sh/docs/under-the-hood/the-planner.md): Cost in microseconds, recall in the objective, and how to read explain.
- [Embeddings and the vector index](https://vitruvio.sh/docs/under-the-hood/embeddings-and-vectors.md): Two spaces, the model tag, and why the layer travels.
- [Benchmarking and calibration](https://vitruvio.sh/docs/under-the-hood/benchmarking.md): Measuring recall, and calibrating the cost model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.