Installation

Stormbuffer ships as a packaged release for Linux x86-64, macOS on Intel or Apple silicon, and Windows x86-64. Each archive includes the sbuf CLI, the stormbuffer-mcp adapter, man pages, shell completions, and project documentation.

Install

Download the archive for your platform and its .sha256 file from the GitHub release. On Linux or macOS, verify and unpack it:

archive=stormbuffer-0.1.0-x86_64-unknown-linux-gnu.tar.gz
shasum -a 256 -c "$archive.sha256"
tar -xzf "$archive"
install -m 755 "${archive%.tar.gz}"/bin/* "$HOME/.local/bin/"

On Windows, set $archive to the downloaded ZIP name and compare Get-FileHash -Algorithm SHA256 $archive with the value in the downloaded checksum file. Extract the ZIP and add its bin directory to PATH. The archive’s share directory contains optional man pages and shell completions.

Build from a checkout

Follow Build from source to install the CLI and MCP adapter from a checkout. Man pages and shell completions are available in the GitHub release archives.

Confirm the installation

sbuf --version
sbuf --help
stormbuffer-mcp --version

Online and offline model behavior

Installation does not download a model. Stormbuffer acquires its pinned local embedding model when a global store is initialized or retrieval first needs it.

Stormbuffer verifies the model checksum before use and stores the model in the platform cache.

Environment	Behavior
Online	Store operations work, and the verified model is downloaded when semantic retrieval needs it.
Offline with the model cached	Store operations and hybrid retrieval work without network access.
Offline without the model cached	Project initialization and canonical record operations work. Retrieval reports that the verified model is unavailable until the machine is online.

If a global init cannot acquire the model, it still initializes the store and does not change its canonical Markdown. Re-run sbuf init after network access is restored.

Continue with the quick start to choose and initialize a store.

Upgrade

Before an upgrade, export the selected store as described in Backup and recovery. Replace the installed programs, then run sbuf status and sbuf doctor. Add --project when checking a project store.

Roll back

Restore the previous programs and repeat the status and doctor checks. Read the newer release notes before rolling back across a record-format change.

Uninstall

Remove sbuf, stormbuffer-mcp, and any man pages or completions you installed. This leaves stores and their records in place. Use sbuf root before uninstalling if you need to locate the global store; project stores live in .sbuf/.