Skip to content
Get packs

Guide · Open source

How to use MindsHub: web, desktop or build from source

Updated · written with AI from the project's own documentation and checked against our catalogue data

MindsHub is an open-source agent workspace for research, analysis, content and software development. It lets you choose among many models and providers instead of being tied to one. This guide explains the three ways to start using it and what each one involves, and how to build the full stack from source.

MindsHubmindsdb/mindshub · ★ 39.8k · MIT

Quick start

  1. 1Pick a way to run it. Use the web app for zero setup, a desktop installer on macOS or Windows, or build from source on Linux or for development.
  2. 2Clone the repository. Run git clone with --recurse-submodules so all included modules are downloaded.
  3. 3Enter the project folder. Change into the minds directory with cd minds.
  4. 4Install dependencies. Run make setup to install dependencies.
  5. 5Start the app. Run make dev for the desktop app with hot reload, or make dev-web for the browser version.

Choose how you want to run MindsHub

The README lists three entry points. The web app needs nothing installed: open console.mindshub.ai and sign in. A desktop app is offered for macOS (a .pkg file) and Windows (a .exe file). Linux users are pointed to building from source.

  • Web: open console.mindshub.ai and sign in
  • macOS: download the desktop app (.pkg)
  • Windows: download the desktop app (.exe)
  • Linux or developers: build from source

Build MindsHub from source

The repository is a superproject that pulls in the desktop/web app, the agent backend and the data engine. Building from source requires Git, Make and Python 3.10 to 3.13. Clone the repository with its submodules, then install dependencies.

  • Prerequisites: Git, Make, Python 3.10–3.13
  • Clone with submodules so the included modules are fetched
  • Run make setup to install dependencies
git clone --recurse-submodules https://github.com/mindsdb/minds.git cd minds make setup

Run the app in development mode

make dev runs the desktop app (Electron) with hot reload, so changes to local source show up live. make dev-web runs the web app in a browser with hot reload instead.

  • make dev: desktop app with hot reload
  • make dev-web: web app in the browser with hot reload
  • make build: production build
  • make dist-mac and make dist-win: package for macOS or Windows
make dev

Work on feature branches with submodules

The repo pins each module to a commit. To work on a module branch, copy the template dev.env.example to a gitignored dev.env and set your REF. Then make use checks out those refs across the submodules. Submodules are set to ignore = all, so branch work does not show in the parent git status.

  • make use: check out dev.env refs across submodules
  • make refs: show which refs the next run will use
  • make baseline: reset submodules to the pinned commits
  • make pin: record current submodule commits as pins
cp dev.env.example dev.env

Reset a broken install

make flush removes the local runtime and deletes app state, including conversations and saved provider keys. It prompts for confirmation unless you pass FORCE=1. Use it to test a clean install or recover from a broken one. Back up anything you need first.

  • Removes the cowork-server uv tool and backend .venv folders
  • Deletes app state in ~/.anton (provider keys) and ~/.cowork (database, projects)
  • The next make setup or app launch reinstalls everything
make flush

What people use it for

  • Automating reading and writing work such as reports and recurring workflows
  • Turning agent output into documents, dashboards or apps and publishing them to a live URL
  • Comparing or switching between frontier and open models through the Model Router
  • Building and running the full MindsHub stack from source as a developer
  • Deploying in a cloud, VPC, on-prem or air-gapped environment

Frequently asked questions

How do I install MindsHub?

The quickest route is the web app at console.mindshub.ai, with no installation. On macOS and Windows you can download the desktop app. For other setups, clone the repository with git clone --recurse-submodules, then run make setup and make dev.

What do I need to run MindsHub from source?

The README lists Git, Make and Python 3.10 to 3.13. You clone the repository with submodules, install dependencies with make setup, and run the app with make dev.

Is MindsHub free?

The README says it is free to start. A Pro tier adds all frontier models and private artifacts, and pricing is listed on the MindsHub pricing page. The project itself is released under the MIT License.

Can I run MindsHub offline?

The README does not describe offline operation. It describes connections to hosted providers, so it is not a documented fully offline option.

Is there a Linux installer?

The README does not provide a packaged Linux installer. It points Linux users to building from source.

How does MindsHub compare to Open WebUI, LibreChat, AnythingLLM or Jan?

These are listed as comparable projects. MindsHub's distinguishing features in the README are its agent workspace, Model Router, swappable open agents and scheduled tasks. This guide does not benchmark them against each other.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

MindsHub suits knowledge workers who want to automate reading and writing tasks, developers who want to build the full stack, and teams that need flexible deployment. It is a poor fit if you need a fully offline, minimal tool, a fully documented self-hosting path, or a packaged Linux installer.

Install options & downloads