> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modusbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> A complete guide on installing the ModusBrain command-line interface across macOS, Linux, and Windows platforms.

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:

<Tabs>
  <Tab title="npm (Recommended)">
    Install the CLI globally on your system using the standard Node Package Manager:

    <Tabs>
      <Tab title="macOS, Linux, WSL">
        ```bash theme={null}
        npm install -g @genthropic/modusbrain
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        Open an Administrator PowerShell console and execute the global installation command:

        ```powershell theme={null}
        npm install -g @genthropic/modusbrain
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Bun">
    Install the global CLI utility using Bun's native package management suite for faster execution times:

    <Tabs>
      <Tab title="macOS, Linux, WSL">
        ```bash theme={null}
        bun install -g @genthropic/modusbrain
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        Execute the global installation within your PowerShell console:

        ```powershell theme={null}
        bun install -g @genthropic/modusbrain
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="From Source">
    For development work, clone the official GitHub repository and link the package files locally:

    ```bash theme={null}
    git clone https://github.com/thebuildceo/modusbrain.git
    cd modusbrain
    bun install --ignore-scripts
    bun link
    ```
  </Tab>
</Tabs>

<Note>
  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.
</Note>

***

## 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:

```bash theme={null}
modusbrain --version
modusbrain doctor
```

### 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:

| Path            | Purpose                                                                                                                   |
| :-------------- | :------------------------------------------------------------------------------------------------------------------------ |
| `~/.modusbrain` | Default directory used for configuration variables, database storage files, and local schemas.                            |
| `~/.gbrain`     | Legacy home directory path — automatically detected as a fallback if you have configuration files from previous versions. |

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](/env-vars).