MindsHub Cowork: a superproject Makefile that ties an Electron app, an agent backend and a data vault together

What the mindsdb/mindshub repository actually is

Most people arriving from a search for MindsHub want the product. This repository is not that. The README calls it the platform superproject: it pulls together the desktop and web app, the agent backend and the data engine so the whole stack can be built from source. The product itself is MindsHub Cowork, a workspace where you delegate projects (apps, websites, research, analysis, reporting, scheduled operations) and collect finished results. The repository is the assembly point for that product, and the distinction matters because it decides whether you need to clone anything at all.

The README offers four entry points. The web app at console.mindshub.ai requires nothing installed. macOS and Windows users get a .pkg and an .exe from downloads.mindsdb.com. Linux has no package: the README points Linux users at the build-from-source section, which is the one path that makes this repository mandatory. The stated audience is knowledge workers rather than engineers, but the repository is written for people who build and package the stack.

Four submodules do the real work: frontend, backend/core_api, backend/core_agent and backend/data-vault. The Makefile assigns each a variable name (FRONTEND, API, AGENT, VAULT) and the superproject pins each to a commit. Everything else in the tree, from docker/ to dev.env.example, exists to build, run or package those four.

How the superproject, the pins and the model router fit together

The mechanism is git submodules plus a Makefile that knows how to install and launch them. Because the submodules are configured with ignore = all, work on a module branch never appears in the parent git status, and the pins move only through make pin. The Makefile comments describe the design intent directly: per-developer ref choice lives in dev.env, which is gitignored, so each developer can work on their own module branches without touching shared files or CI.

The routing of refs is the part worth reading closely. A single REF variable in dev.env sets all modules, and API_REF, AGENT_REF and FRONTEND_REF override it per module, each defaulting to REF. Two run paths follow those refs. make dev and make dev-web run the local submodule source, so they follow whatever branch is checked out. The Electron desktop server is different: the Makefile exports COWORK_SERVER_REF and ANTON_REF so that make app and make server install the matching branch through a uv tool. The Makefile only injects an anton override when AGENT_REF is not main, because uv rejects a redundant --with flag.

On the product side, the README describes a Model Router that switches between frontier models (Claude, GPT, Gemini) and open models (DeepSeek, Qwen, Kimi) without wiring a key per provider, and open agents that run interchangeable harnesses, Anton by default and Hermes as the alternative, swappable from a dropdown. A connected data vault links systems such as BigQuery, Postgres, Gmail, Drive, HubSpot, Notion and Linear, with credentials scoped per connection so agents never see raw keys. The repository does not document how the router selects a provider or how vault scoping is enforced, so treat those as product claims rather than verifiable implementation detail.

Installing MindsHub Cowork from source and running it once

The README's build path starts with a clone that must include submodules, because the superproject is useless without them. The --recurse-submodules flag is not optional here; a plain clone leaves four empty directories.

git clone --recurse-submodules https://github.com/mindsdb/minds.git
cd minds

Dependencies come from a single make target, which the README lists as the second step. Expect it to install the frontend's node_modules and the Python virtual environments under backend/*/.venv, since the Makefile defines stamp files for exactly those paths.

make setup

Running it is a choice between an Electron window and a browser tab. The README's table gives make dev or make watch for the desktop app with hot reload, and make dev-web for the web SPA in a browser, both against local source.

make dev-web

If you prefer containers, the repository ships a docker-compose.yml with two services. The api service builds from docker/api.Dockerfile, binds port 26866, stores SQLite at sqlite:////home/cowork/.cowork/cowork.db in a named volume, and exposes a /health endpoint that the compose healthcheck polls. The web service builds from docker/web.Dockerfile and maps port 80 in the container to 3000 on the host, starting only after api reports healthy.

docker compose up

The compose file also shows where a provider key goes: ANTON_ANTHROPIC_API_KEY is present but commented out, so a container started as-is has no Anthropic key configured.

make flush deletes your conversations, and other constraints

The sharpest limitation is documented in the README itself. make flush removes the local runtime (the cowork-server uv tool and the backend virtual environments) and deletes app state in ~/.anton, which holds provider keys, and ~/.cowork, which holds the database, hermes and projects. The README warns in plain terms that this deletes your conversations and saved keys. It prompts for confirmation, and FORCE=1 skips the prompt. The documented purpose is testing the from-scratch install flow or recovering from a broken install, and the next make setup or app launch reinstalls everything. That is a reasonable developer affordance and a poor fit for anyone treating a local install as durable storage.

A second constraint is platform packaging. The README lists make dist-mac and make dist-win for packaging, and make pack-local for building a macOS .app from local uncommitted source. Linux appears only as build-from-source, with no distribution package described. If your team is standardized on Linux desktops, you are maintaining the build path rather than consuming a release.

A third is the submodule model itself. Pins move only via make pin, and the parent repository stays clean because submodules are ignored. That keeps git status readable but means a superproject commit tells you almost nothing about what changed inside a module. The README defers the full workflow to CLAUDE.md, which is a signal that the contributor process is more involved than the four-line quick start suggests.

Finally, the repository is a Makefile-dominant project. The GitHub language breakdown will read as Makefile, not Python or TypeScript, which makes automated dependency and security scanning less useful than it would be on a normal application repository.

How MindsHub Cowork differs from MindsDB and from wiring an agent yourself

The most common alternative people search for is MindsDB itself. They are related but not the same thing. MindsDB is the data-and-model layer that has been around longer and is what most existing tutorials, install guides and community answers describe. MindsHub Cowork is the workspace built on top: delegated projects, artifacts published to a live URL, cross-session memory, a reusable skill library and scheduled tasks. If your problem is querying or predicting over data inside a database, MindsDB is the closer match. If your problem is getting a multi-step report or internal tool produced and shared, Cowork is the layer that addresses it.

The other alternative is assembling the pieces yourself: a provider SDK, an agent framework, a scheduler and a hosting target. That gives you control over every hop and no shared abstraction to fight. What you give up is the Model Router, which the README frames as avoiding a key per provider, and the data vault's per-connection credential scoping. Whether that trade is worth it depends on how many providers and data sources you actually connect. For one provider and one database, the router earns little. For five of each, it is the reason to use the product.

A third comparison is deployment shape. The README states Cowork is built for cloud, VPC, on-prem, air-gapped and hybrid infrastructure, and the compose file shows the api and web services running side by side with a local SQLite database. That is a self-hostable shape. A hosted-only agent platform would not give you the compose file at all.

Maintenance, upgrades and the MIT licence

The repository is not archived. Its last push was on 2026-04-23, which is roughly five months before today, and the most recent release in the list is v26.1.0 on the same date, preceded by v26.1.0rc1 on 2026-04-17 and v26.0.1 on 2026-03-03. The release cadence visible here is a minor version roughly every two months with a release candidate shortly before, though three data points do not establish a schedule. The gap since the last push is long enough that you should check the repository yourself before planning around it.

Upgrade cost is concentrated in the submodule pins. Moving the superproject forward means the pins move with it, and if you have local work on a module branch, you reconcile it against the new pin. The Makefile's make baseline resets submodules to the pinned commits, which is the escape hatch when a branch experiment goes wrong, and make refs shows which refs the next run will use. The dev.env mechanism means an upgrade does not have to touch shared files, but it also means the refs you are running are invisible unless you ask for them.

The licence is MIT, which is permissive and permits commercial use and modification. The README separately mentions a hosted pricing page and Pro tier that adds frontier models and private artifacts, and an enterprise contact for SLAs and custom deployments. Those are commercial offerings around the project, not restrictions in the licence. Nothing here is legal advice; read the LICENSE file and the pricing page if the distinction between the open source code and the paid service matters to your organisation.

Editorial conclusion

Adopt this repository if you intend to run the whole Cowork stack from source, or if you need to build the Linux desktop app, which the README lists as build-from-source only. Do not adopt it if you only want to use the product; the hosted console and the macOS and Windows packages need no clone. Before committing, verify two things in the repository itself: that git submodule status resolves every pinned commit, and that the COWORK_SERVER_REF and ANTON_REF values exported by the Makefile match the branch you intend to run. Then run make refs, which the README describes as showing which refs the next run will use, before you start anything.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes