# Install vibe {#root} @status:doc/work @audience:user [p01] vibe is one program with no runtime to install. On Windows you download an archive and unpack it; on any platform with a Rust toolchain you build it from the source. When it is done, one command prints the version. [p02] ```prompt Install vibe on this machine: on Windows from the latest release archive at github.com/vibevm/vibevm, otherwise by building the source checkout with its first-run script. Then open a new shell and confirm that `vibe --version` prints a version. ``` - needs: network access to github.com; on a platform other than Windows, git and a Rust toolchain outcome: `vibe --version` prints `vibe 1.0.0` in a new terminal, and `vibe self doctor` reports no problems - assert: `vibe --version` - assert: `vibe self doctor` ## What happens {#what-happens} [p03] On Windows the agent downloads the release archive, unpacks it, and runs its installer script. The script imports the binary into vibe's own managed folder under `~/.vibe/opt`, marks it active, and adds one folder of small launcher scripts to your user `PATH`. Everywhere else the agent clones the source repository and runs its first-run script, which builds the program and installs it through the same manager. Either way, the result is the same layout: versions under `~/.vibe/opt/vibevm/`, launchers in `~/.vibe/opt/bin/`, and a pointer that says which version is current. > [p04] `$VIBEVM_INSTALL_ROOT` (the install BASE) defaults to `~/.vibe` → root > `~/.vibe/opt` in normal use (owner ruling 2026-08-20, the release-1.0 > install path; until then the default base was the bare home dir → `~/opt`). > An explicit override keeps its meaning — `/opt` — and one env var > still relocates everything; tests pin it to a temp dir. A managed binary > keeps recognising its own root by shape (the trailing `opt` component), > so both generations of store keep working. > > [p05] vibe runs on Windows, macOS and Linux. The one-line cold start is a script at a stable address, `https://vibevm.org/install.sh` for Bash and `install.ps1` for PowerShell: it downloads the release manifest, verifies a small bootstrap binary by size and digest, and that binary verifies and installs the full bundle. Package managers such as Homebrew and WinGet come later. > [p06] **Decision:** M0 builds and runs on macOS, Linux, and Windows. > > > [p07] Stable endpoints provide one-line native cold start: Bash for Linux/macOS/WSL > and PowerShell for Windows. Each bounded script downloads > `DISTRIBUTIONS.json`, verifies a small raw `vibe` bootstrap by size/SHA-256, > then that Rust binary verifies and atomically installs the full bundle. > > > [p08] The scripts are shipped release assets `install.sh` and `install.ps1` and > are exposed by stable `https://vibevm.org/install.*` redirects. Homebrew, > WinGet, and CMD installers remain outside this slice. > > ## By hand {#by-hand} ### On Windows (os:windows) {#windows} [p09] 1. Download `vibe--windows-x86_64.zip` from the releases page of `github.com/vibevm/vibevm`. [p10] 2. Unpack the archive into a folder of your choice. [p11] 3. In that folder run the installer: [p12] ```sh powershell -ExecutionPolicy Bypass -File .\install.ps1 ``` ```output ``` [p13] 4. Open a new terminal, so that the changed `PATH` is read. [p14] 5. Check the result: [p15] ```sh vibe --version ``` ```output vibe 1.0.0 ``` [p16] The archive also contains `SHA256SUMS.txt`. Compare the digest of `vibe.exe` with the line in that file before you run the installer. The installer does the same check. ### From the source, on any platform {#from-source} [p17] 1. Install git and a Rust toolchain. OpenSSL is not needed. > [p18] A from-source build needs **git**, a **Rust toolchain** (rustc + cargo, > stable ≥ 1.93, edition 2024 — via rustup so the pin resolves), and a > **system linker / C toolchain** (Windows: VS Build Tools; macOS: Xcode CLT; > Linux: `build-essential`). A native binary install needs none of those; > its bootstrap uses only the platform download/TLS facilities. > > [p19] 2. Clone the repository: `git clone https://github.com/vibevm/vibevm.git` and enter the folder. [p20] 3. Run the first-run script: `bash tools/first-run.sh` on Linux and macOS, `.\tools\first-run.ps1` on Windows. It builds the program, installs it into the managed [store](../glossary/index.xml#store) and sets up the launchers. [p21] 4. Open a new terminal and run `vibe --version`, then `vibe self doctor`. [p22] Later, `vibe self update` moves the installation to the newest release, and `vibe self reinstall` downloads the current one again. `vibe self ls` lists the versions on the machine, and `vibe self rollback` returns to the previous one. > [p23] `self install ` — from a source execution, build the selected > ref; from a managed binary execution, an explicit `X.Y.Z` installs that > native release. Flags: `--release` / `--profile ` (source > lane); `--mirror ` (force the source lane); `--force` > (always allocate a fresh immutable `#N`). > > ## Where things go {#where-things-go} [p24] vibe keeps everything it owns under one folder in your home directory, `~/.vibe/`: the installed versions and their launchers under `opt/`, the machine store of fetched packages under `cache/`, [registry](../glossary/index.xml#registry) clones under `registries/`, and your settings files. Nothing is written anywhere else, and the whole folder can be moved by setting the environment variable `VIBE_SETTINGS`. > [p25] **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. > > [p26] The installer never overwrites a running binary and never edits your `PATH` twice: it adds one entry, guarded by a marker, and leaves the rest alone. > [p27] **never clobber** (only our entry is added; the rest of `PATH` is > preserved), > > ## Edge cases and rules {#edge-cases} [p28] If `vibe --version` prints nothing in the terminal where you ran the installer, open a new one: the `PATH` change applies to new shells only. [p29] A ready-built binary from anywhere can join the managed store without a toolchain: `vibe self import ./vibe.exe --tag 1.0.0 --use`. > [p30] `self import --tag ` — put a legacy READY-BUILT local `vibe` > executable into the inventory as an immutable `tag:` instance, reusing the > store/placer/lock/state machinery (built 2026-08-20 for the 1.0.0 > distributive; the install.ps1 of the zip calls it instead of duplicating > `state.toml`). Local by construction: no network, no signature machinery — > the file is streamed through SHA-256 once, and that digest drives > idempotence: same tag + same digest reuses the instance; same mutable tag + > different digest creates a new local `#N` beside the preserved old one. > `--replace-candidate` remains compatibility spelling. Optional `--commit`, `--profile` > (default `release`); inactive by default — `--use` runs the same complete > shim/PATH/pointer/advisory-HOME activation as every other lane. > > [p31] Building an arbitrary git ref is running arbitrary code, as with any build from source. Build from the repository and the branches you trust. > [p32] Building an arbitrary ref is arbitrary code execution — inherent to a build > tool the user invokes deliberately, and accepted. > >