Installation

Requirements

• A published release artifact for your operating system and CPU architecture
• Git for repository and worktree features

Release builds

Binary builds come from the BWO release catalogs. Stable, preview, and nightly are the channels. A channel is available only when its catalog lists a versioned release record whose artifacts are published.

Current catalog: stable v2.1.0 provides BMO binary builds for macOS, Linux, and Windows. Downloads currently require authorized access to the private BWO repository. Preview and nightly have no published releases (latest: null, releases: []).

The executable remains bmo. Use the version-specific install and verification notes.

For a published release:

1. Select the artifact for your operating system and CPU architecture from that version’s release record.
2. Read that version’s prerequisites, executable name, configuration compatibility, and distribution notices.
3. Download the asset from the URL in the release record.
4. Check the SHA-256 digest against the catalog entry, and the publisher signature or attestation when the record includes one.
5. Follow that version’s release notes for installation. Do not reuse commands from a different version.
6. Run the version command and first-run checks in those notes.

The BWO catalogs are the source of truth for which artifacts exist. This book does not publish a substitute download URL.

Maintainer source builds

People with access to the source tree build from a checkout with task build. That path is separate from public binary distribution. The contributor guide in the source tree covers credentials and validation.

Verify the installation

After installing v2.1.0, run bmo --version; the expected output is bmo version v2.1.0. Compare the selected artifact’s complete SHA-256 digest with the BWO versioned record before execution. No new publisher signature or cryptographic attestation is supplied by this distribution.

Embedding service memory

The local embedding sidecar (bmo-embedding) runs as a separate process and initializes lazily when an embedding operation first needs it. Its memory use depends on the model, index, and workload; budget for it separately from the main BMO process.

To disable this embedding service:

[options.embedding]
enabled = false

Disabling the embedding service does not affect persistent-memory embeddings ([options.persistent_memory.embeddings]), which use a separate code path and can delegate to remote providers.

Update BMO

Follow the selected BWO version’s upgrade notes. Retain the previous executable and back up data before replacement; rollback of migrated data is not independently qualified by this binary distribution.

bmo update-providers does not upgrade the BMO binary. It only refreshes the provider/model catalog metadata:

bmo update-providers

Verify it worked: Run bmo --version after updating to confirm the new version. Run bmo update-providers and check for a success message to confirm the catalog refreshed.

Config and data directories

Global config defaults to ~/.config/bmo/bmo.toml on macOS and Linux, respecting XDG_CONFIG_HOME when set. Existing JSON files remain a fallback. Global application data defaults to ~/.local/share/bmo/, respecting XDG_DATA_HOME; on Windows it uses LOCALAPPDATA.

These environment variables override the global directories:

export BMO_GLOBAL_CONFIG=/custom/config-dir
export BMO_GLOBAL_DATA=/custom/global-data-dir

Run bmo dirs, bmo dirs config, or bmo dirs data to inspect these global paths. bmo dirs data does not report the session runtime data directory.

Project-local runtime data

Session state and logs use options.data_directory, or the --data-dir override. By default, BMO reuses the nearest existing .bmo/ directory found from the working directory upward, or creates one in the working directory. BMO creates a self-ignoring .gitignore inside a new runtime data directory; an existing ignore file is preserved.

bmo --data-dir /absolute/path/to/runtime-data

Deleting this directory removes the session history and other runtime state it contains. Keep a backup if you need that history; changing BMO_GLOBAL_DATA does not move the project’s session database.

Remove BMO

Uninstall stops matching BMO processes and removes the user install: global config, global data, ~/.bmo, and bmo / bmo-embedding binaries in user bin directories. Project .bmo/ directories are removed only for projects you name.

Versioning

See Versioning for details on release channels, semver policy, and upgrade notes.