The newcomer's route

Step 1: understand what you are installing

02Read What VibeVM is first. It takes five minutes and gives you the one idea everything else rests on: instruction text for an agent is a dependency, and dependencies are installed, versioned and shared like libraries. The rule to remember is that installing never edits what you wrote.

03 The owner's hard constraint: installing a dependency must never modify any node's authored spec — the C++ rule that you do not paste a header's text into your #include.

Step 2: install vibe

04Follow Install vibe. On Windows it is an archive and a script; elsewhere it is a clone and a script. You are done when a new terminal answers vibe --version. Everything vibe owns lives under one folder in your home directory, and you can move that folder with one environment variable.

05 The settings home is ~/.vibe (owner, 2026-08-20). This document previously named ~/.config/vibe/config.toml; the code has treated ~/.vibe as canonical all along and the XDG path only as a legacy location an operator is invited to migrate out of. The correction is to this document, not to the tree.

Step 3: create a project and install one package

06Follow Create your first project. Give the prompt to your agent, or run the four commands by hand. The package you install is a way of working; the agent reads it at every session start from then on. Note the plan vibe shows before it writes anything: nothing is installed until you say yes.

07 Decision. A package's identity is the tuple (kind, name, version, content_hash). The content_hash is a digest over the deterministically-ordered concatenation of (rel_path_bytes || 0x00 || file_bytes || 0x00) for every file in the package directory, and the value names the recipe that produced it (PROP-044 §4.7): sha256-tree/1:<hex> is recipe 1, whose exclusion list, path normalisation and traversal order are carried as data in formats/hash_recipes/1.toml; the bare sha256:<hex> is recipe 0, the pre-recipe form, frozen verbatim in code — not configurable, because a frozen recipe that can be edited is not frozen — so that values written before recipes were named stay readable. Two hashes are comparable only at the same recipe; comparing across recipes answers a question nobody asked, and is never done silently. PROP-024 §2.2 re-scopes this to the package's shippable tree — its source, minus build output (.git/, .vibe/, target/, node_modules/, .vibeignore globs) — so a code-bearing package's identity is its source, not its build state; that exclusion lands with the code that implements it. The URL used to fetch the content is informational — recorded in the lockfile for debuggability, not for identity.

Step 4: look at what appeared

08Read What a project contains with the new folder open beside it. Two files are yours, one tree is yours, one tree is vibe's, and the generated files carry the reading list. Knowing who writes what is the difference between a project that stays consistent and one that fights its own tool.

09 Decision. A node's authored spec/ and its materialised dependencies live in physically separate trees. vibe install never writes into any node's authored spec/.

Step 5: see how the agent reads it

10Read The boot lane. The agent opens the instruction file, reads one generated file in full, and follows a list for the rest. It never runs vibe to start. When you later add packages, remove them or update them, the lane is regenerated and the agent's next session reads the new one.

11 Session-start order: the CLAUDE.md / AGENTS.md / GEMINI.md redirect → vibevm/vibespecs/boot/STATIC.xml (if present) → vibevm/vibespecs/boot/INDEX.md and the entries it names, in order.

After the route

12From here the manual branches. To work day to day, the pages under How to cover installing, updating, removing, working offline and publishing. To understand the machinery, the pages under Model explain packages and kinds, registries, the lock file and the machine store, and versions. To let your agent do the work, Give your agent the vibevm skill comes next. And whenever a command refuses, From an error message to the rule names the rule it enforced.