Skip to main content
ModusBrain is designed to run as a global command-line interface (CLI) application compiled on top of the Bun runtime. To accommodate different system architectures and deployment workflows, you can install ModusBrain using the Node Package Manager (npm), the Bun package manager, or by building the application directly from the source repository.

​
Before you begin

Before initiating the installation process, ensure your workstation satisfies the following prerequisites to guarantee a smooth setup:
  • Runtime Environment — Make sure either Bun (version 1.3.10 or higher) or Node.js (version 18.0.0 or higher) is installed on your local machine.
  • Terminal Access — A terminal session, PowerShell console, or command prompt must be open with appropriate permissions to install global packages.
  • API Credentials — You will need an API key from a supported embedding provider (such as ZeroEntropy or OpenAI) to enable query vectorization and semantic search indexing.

​
Supported Installation Methods

Choose the package manager or installation methodology that best aligns with your development environment:
Install the CLI globally on your system using the standard Node Package Manager:
If the global installation’s post-install hooks encounter permission blocks or file system errors on Windows environments, run the installation command with the --ignore-scripts flag: npm install -g @genthropic/modusbrain --ignore-scripts (or the equivalent Bun syntax), and then execute modusbrain init manually.

​
Post-Installation Steps

​
1. Verification

Once the installation completes, verify that the CLI binary is correctly registered in your system path by checking its version and running the system diagnostics suite:

​
2. Configuration and File Locations

ModusBrain stores persistent data, including schema caches, system settings, and local database storage directories, within your system’s user home directory: For environment-driven configurations, we recommend setting options using the MODUSBRAIN_* namespace. The system will continue to recognize legacy GBRAIN_* variables as a backwards-compatible fallback. For a complete list of configuration options, consult the Environment variables guide.